Skip to content

Classes

HexColor 

HexColor(hex_code)

Represents a hexadecimal color code.

Initialize a HexColor.

Parameters:

Name Type Description Default
hex_code str

Hex color string, e.g., "#FFF" or "#FFFFFF".

 required

Raises:

Type Description
ValueError

If hex_code is not valid.
Source code in opencatwebjson/classes.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
def __init__(self, hex_code: str):
    """
    Initialize a HexColor.

    Args:
        hex_code (str): Hex color string, e.g., "#FFF" or "#FFFFFF".

    Raises:
        ValueError: If hex_code is not valid.
    """
    if not (hex_code.startswith("#") and len(hex_code) in (4, 7)):
        raise ValueError("Invalid hex color")
    self.hex = hex_code.upper()

Range01 

Range01(value)

Represents a float value restricted to the range [0, 1].

Source code in opencatwebjson/classes.py 
31
32
33
34
def __init__(self, value: float):
    if not 0 <= value <= 1:
        raise ValueError("Value must be between 0 and 1")
    self.value = value

ScaleOffset 

ScaleOffset(scale, offset)

Represents a scale (0-1) with an offset for positioning or sizing.

Parameters:

Name Type Description Default
scale Number

Scale factor (0 to 1).

 required
offset Number

Pixel offset.

 required

Raises:

Type Description
ValueError

If scale is not between 0 and 1.
Source code in opencatwebjson/classes.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
def __init__(self, scale: Number, offset: Number):
    """
    Args:
        scale (Number): Scale factor (0 to 1).
        offset (Number): Pixel offset.

    Raises:
        ValueError: If scale is not between 0 and 1.
    """
    if not 0 <= scale <= 1:
        raise ValueError("Scale must be between 0 and 1")
    self.scale = scale
    self.offset = offset

Vector2 

Vector2(x, y)

Represents a 2D vector using scale + offset for x and y axes.

Source code in opencatwebjson/classes.py 
67
68
69
def __init__(self, x: ScaleOffset, y: ScaleOffset):
    self.x = x
    self.y = y

to_pixels 

to_pixels(parent_width, parent_height)

Convert scale+offset to absolute pixel coordinates.

Parameters:

Name Type Description Default
parent_width Number

Width of parent container in pixels.

 required
parent_height Number

Height of parent container in pixels.

 required

Returns:

Type Description
tuple[Number, Number]

tuple[Number, Number]: Pixel coordinates (x, y).
Source code in opencatwebjson/classes.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def to_pixels(self, parent_width: Number, parent_height: Number) -> tuple[Number, Number]:
    """
    Convert scale+offset to absolute pixel coordinates.

    Args:
        parent_width (Number): Width of parent container in pixels.
        parent_height (Number): Height of parent container in pixels.

    Returns:
        tuple[Number, Number]: Pixel coordinates (x, y).
    """
    px = self.x.scale * parent_width + self.x.offset
    py = self.y.scale * parent_height + self.y.offset
    return px, py

Size2 

Size2(width, height)

Represents a 2D size using scale + offset for width and height.

Source code in opencatwebjson/classes.py 
93
94
95
def __init__(self, width: ScaleOffset, height: ScaleOffset):
    self.width = width
    self.height = height

to_pixels 

to_pixels(parent_width, parent_height)

Convert scale+offset to absolute pixel size.

Parameters:

Name Type Description Default
parent_width Number

Width of parent container in pixels.

 required
parent_height Number

Height of parent container in pixels.

 required

Returns:

Type Description
tuple[Number, Number]

tuple[Number, Number]: Size in pixels (width, height).
Source code in opencatwebjson/classes.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def to_pixels(self, parent_width: Number, parent_height: Number) -> tuple[Number, Number]:
    """
    Convert scale+offset to absolute pixel size.

    Args:
        parent_width (Number): Width of parent container in pixels.
        parent_height (Number): Height of parent container in pixels.

    Returns:
        tuple[Number, Number]: Size in pixels (width, height).
    """
    w = self.width.scale * parent_width + self.width.offset
    h = self.height.scale * parent_height + self.height.offset
    return w, h

Rotation 

Rotation(degrees)

Represents a rotation in degrees.

Source code in opencatwebjson/classes.py 
119
120
def __init__(self, degrees: Number):
    self.degrees = float(degrees)

set 

set(degrees)

Set the rotation to a specific angle.

Source code in opencatwebjson/classes.py 
125
126
127
def set(self, degrees: Number):
    """Set the rotation to a specific angle."""
    self.degrees = float(degrees)

add 

add(delta)

Add delta degrees to the current rotation.

Source code in opencatwebjson/classes.py 
129
130
131
def add(self, delta: Number):
    """Add delta degrees to the current rotation."""
    self.degrees += delta

normalized_360 

normalized_360()

Return rotation normalized to [0, 360) degrees.

Source code in opencatwebjson/classes.py 
133
134
135
def normalized_360(self) -> float:
    """Return rotation normalized to [0, 360) degrees."""
    return self.degrees % 360

normalized_180 

normalized_180()

Return rotation normalized to [-180, 180) degrees.

Source code in opencatwebjson/classes.py 
137
138
139
140
141
142
def normalized_180(self) -> float:
    """Return rotation normalized to [-180, 180) degrees."""
    deg = self.degrees % 360
    if deg > 180:
        deg -= 360
    return deg

to_radians 

to_radians()

Convert rotation to radians.

Source code in opencatwebjson/classes.py 
144
145
146
def to_radians(self) -> float:
    """Convert rotation to radians."""
    return math.radians(self.degrees)

GradientStop 

GradientStop(position, value)

Represents a stop in a gradient with a position and a value.

Parameters:

Name Type Description Default
position float

Position along gradient (0 to 1).

 required
value

Value at this stop (float for transparency, str for color).

 required

Raises:

Type Description
ValueError

If position is not between 0 and 1.
Source code in opencatwebjson/classes.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
def __init__(self, position: float, value):
    """
    Args:
        position (float): Position along gradient (0 to 1).
        value: Value at this stop (float for transparency, str for color).

    Raises:
        ValueError: If position is not between 0 and 1.
    """
    if not 0 <= position <= 1:
        raise ValueError("Position must be between 0 and 1")
    self.position = position
    self.value = value

TransparencyGradient 

TransparencyGradient(stops)

Represents a gradient of transparency values (0-1).

Source code in opencatwebjson/classes.py 
173
174
175
176
177
def __init__(self, stops: List[GradientStop]):
    for stop in stops:
        if not isinstance(stop.value, (float, int)):
            raise TypeError("TransparencyGradient values must be float or int")
    self.stops = sorted(stops, key=lambda s: s.position)

get_value_at 

get_value_at(position)

Get interpolated transparency at a given position.

Parameters:

Name Type Description Default
position float

Position along gradient (0 to 1).

 required

Returns:

Name Type Description
float float

Interpolated transparency value.
Source code in opencatwebjson/classes.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def get_value_at(self, position: float) -> float:
    """
    Get interpolated transparency at a given position.

    Args:
        position (float): Position along gradient (0 to 1).

    Returns:
        float: Interpolated transparency value.
    """
    if not 0 <= position <= 1:
        raise ValueError("Position must be between 0 and 1")
    if position <= self.stops[0].position:
        return self.stops[0].value
    if position >= self.stops[-1].position:
        return self.stops[-1].value
    for i in range(len(self.stops)-1):
        s0, s1 = self.stops[i], self.stops[i+1]
        if s0.position <= position <= s1.position:
            t = (position - s0.position) / (s1.position - s0.position)
            return s0.value + t * (s1.value - s0.value)

ColorGradient 

ColorGradient(stops)

Represents a gradient of color values (hex strings).

Source code in opencatwebjson/classes.py 
208
209
210
211
212
def __init__(self, stops: List[GradientStop]):
    for stop in stops:
        if not isinstance(stop.value, str):
            raise TypeError("ColorGradient values must be hex strings")
    self.stops = sorted(stops, key=lambda s: s.position)

get_value_at 

get_value_at(position)

Get color at a given position.

Parameters:

Name Type Description Default
position float

Position along gradient (0 to 1).

 required

Returns:

Name Type Description
str str

Hex color at the given position.
Source code in opencatwebjson/classes.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
def get_value_at(self, position: float) -> str:
    """
    Get color at a given position.

    Args:
        position (float): Position along gradient (0 to 1).

    Returns:
        str: Hex color at the given position.
    """
    if not 0 <= position <= 1:
        raise ValueError("Position must be between 0 and 1")
    for stop in reversed(self.stops):
        if position >= stop.position:
            return stop.value
    return self.stops[0].value