teller

Teller

ColorTeller

A middleware for colorteller web service and benchmarking colors. It takes the color representations on the colorteller web service and converts them to an easy-to-use object.

There are two different methods to instantiate a ColorTeller object:

1. Provide a list of hex strings.
2. Provide a dictionary or json string from the colorteller web service.

Here are some examples:

1. Using a list of hex strings:

   from colorteller import teller
   
   hex_strings = [
       "#8de4d3", "#344b46", "#74ee65", "#238910", "#a6c363", "#509d99"
   ]
   ct = teller.ColorTeller(hex_strings=hex_strings)
   

2. Using a json string:

   from colorteller import teller
   
   ct_raw = '{"author":"KausalFlow","colors":[{"hex":"#8de4d3","name":""},{"hex":"#344b46"},{"hex":"#74ee65"},{"hex":"#238910"},{"hex":"#a6c363"},{"hex":"#509d99"}],"date":1637142696,"expirydate":-62135596800,"file":"bobcat-yellow","hex":["8de4d3","344b46","74ee65","238910","a6c363","509d99"],"images":null,"objectID":"e0e129c8ed58316127909db84c67efcb","permalink":"//localhost:1234/colors/bobcat-yellow/","publishdate":"2021-11-17T10:51:36+01:00","summary":"This is an experiment","tags":null,"title":"Bobcat Yellow"}'
   hex_results = [
       "#8de4d3", "#344b46", "#74ee65", "#238910", "#a6c363", "#509d99"
   ]
   ct = teller.ColorTeller(ct_raw)
   

Note

While we can use this to get some properties of the palette, this is mostly for downstream tasks.

Parameters:

Name	Type	Description	Default
colorteller_raw	Union[dict, str]	A dict (or json string of dict) of the raw response from colorteller web service, defaults to [DefaultParamVal]	required
hex_strings	list	A list of hex strings for the color palette.	required

hex property readonly

a list of hex strings of the palette

rgb property readonly

a list of rgb tuples of the palette

from_hex(self, hex_strings)

set hex_strings property using a list of hex_strings.

There is no return value. The hex_strings property is set using the input.

Parameters:

Name	Type	Description	Default
hex_strings	list	A list of hex strings for the color palette.	required

Source code in colorteller/teller.py

def from_hex(self, hex_strings: list) -> None:
    """set `hex_strings` property using a list of hex_strings.

    There is no return value. The `hex_strings` property is set using the input.

    :param hex_strings: A list of hex strings for the color palette.
    """
    self.hex_strings = hex_strings

get_hex_strings(self, colorteller_raw)

Extract hex_strings from colorteller web service json or dict representation of the color palette.

Parameters:

Name	Type	Description	Default
colorteller_raw	Union[dict, str]	A dict (or json string of dict) of the raw response from colorteller web service.	required

Returns:

Type	Description
list	A list of hex strings for the color palette.

Source code in colorteller/teller.py

def get_hex_strings(self, colorteller_raw: Union[dict, str, None]) -> list:
    """Extract hex_strings from colorteller web service json or dict representation of the color palette.

    :param colorteller_raw: A dict (or json string of dict) of the raw response from colorteller web service.
    :return: A list of hex strings for the color palette.
    :rtype: list
    """
    if colorteller_raw is None:
        return []
    colorteller_raw = colorteller_raw
    colors_raw = colorteller_raw.get("colors", [])
    self.hex_strings = [color.get("hex") for color in colors_raw]

    return self.hex_strings

str_to_json(data_raw) staticmethod

convert the json string to dictionary

Parameters:

Name	Type	Description	Default
data_raw		A json string of the raw response from colorteller web service.	required

Returns:

Type	Description
dict	dictionary of the raw response from colorteller web service.

Source code in colorteller/teller.py

@staticmethod
def str_to_json(data_raw):
    """convert the json string to dictionary

    :param data_raw: A json string of the raw response from colorteller web service.
    :return: dictionary of the raw response from colorteller web service.
    :rtype: dict
    """
    return json.loads(data_raw)

Colors

A color palette container with benchmark results.

To instantiate a Colors object, provide a list of hex strings (color_palette) or a ColorTeller object (colorteller).

Warning

If colorteller is provided, the color_palette argument will be ignored.

from colorteller import teller

hex_strings = [
    "#8de4d3", "#344b46", "#74ee65", "#238910", "#a6c363", "#509d99"
]
ct = teller.ColorTeller(hex_strings=hex_strings)
c = teller.Colors(colorteller=ct)

We could get the metrics from the Colors object.

from colorteller.utils import benchmark

m = c.metrics(methods=[benchmark.PerceptualDistanceBenchmark])

Parameters:

Name	Type	Description	Default
color_palette	list	A list of hex strings.	required
colorteller	Union[Col,Teller]	an ColorTeller object	required

LabColor property readonly

a list of LabColor objects

hex property readonly

a list of hex strings

rgb property readonly

a list of rgb tuples

sRGBColor property readonly

a list of sRGBColor objects

metrics(self, methods=None)

Calculates a list of metrics using the methods provided.

Parameters:

Name	Type	Description	Default
methods	Optional[list]	A list of methods to use to calculate the metrics.	None

Returns:

Type	Description
list	A list of metrics.

Source code in colorteller/teller.py

def metrics(self, methods: Optional[list] = None):
    """Calculates a list of metrics using the methods provided.

    :param methods: A list of methods to use to calculate the metrics.
    :type methods: list
    :return: A list of metrics.
    :rtype: list
    """
    if methods is None:
        methods = []

    metrics = []
    for m in methods:
        m_b = m(self)
        metrics.append(m_b.metric())

    return metrics