Color

Qualified name: algan.constants.color.Color

class Color(rgb, glow=0, opacity=1, *args, **kwargs)

Bases: Tensor

A color, as five channels: red, green, blue, glow and opacity.

Everything in Algan that takes a color – a Mob’s color and stroke_color, a material’s, a light’s, a Scene’s background – accepts one of these, or anything the constructor below accepts. The named palette (BLUE, RED_E, WHITE, …) is made of them.

Glow and opacity are channels rather than separate attributes so they travel with the color through ordinary arithmetic: BLUE * 0.5 dims the color and halves its alpha, and interpolating between two colors interpolates their emissive strength too. When you want to change one channel alone, use set_opacity() or assign to glow.

A Color is a torch.Tensor subclass, so it takes part in tensor arithmetic and can carry batch dimensions – a (*, 5) array of them is what paints one color per vertex or per texel.

Parameters:

• rgb (str | tuple[float, ...] | list[float] | torch.Tensor | np.ndarray) – The color. Accepts a hex string ("#58C4DD", with an optional eighth digit for alpha), a CSS color name ("teal"), an (r, g, b) sequence in [0, 1], an (r, g, b, a) or (r, g, b, glow, a) sequence, or a tensor of any of those widths. A four- or five-wide value supplies opacity (and glow) itself.

• glow – Additive emissive brightness, fed to the bloom accumulator. Unbounded above; 0 is a non-emissive surface. Defaults to 0.

• opacity – Alpha, in [0, 1]: 0 invisible, 1 fully opaque. Defaults to 1, except where rgb carried an alpha of its own.

• *args – Passed to torch.Tensor.__new__().

• **kwargs – Passed to torch.Tensor.__new__().

rgb

The first three channels, as a plain tensor. Assignable.

glow

The fourth channel, shape (*, 1). Assignable.

opacity

The fifth channel, shape (*, 1), in [0, 1]. Assignable.

Raises:

.InvalidColorError – If a string is neither a hex code nor a known CSS color name.

Parameters:

rgb (str | tuple[float, ...] | list[float] | torch.Tensor | np.ndarray)

See also

set_opacity()

Change the alpha alone, leaving the rest.

add_defaults()

Pad a bare RGB or RGBA tensor to five channels.

Examples

Three ways of spelling a color, and a glowing one:

Example: Example1Color

from algan import *

Square(color=BLUE).move(LEFT * 2.5).spawn()
Square(color="#58C4DD").spawn()
Square(color=Color((1, 0.4, 0.2), glow=3)).move(RIGHT * 2.5).spawn()

Scene.save_video()

Methods

add_defaults	Widen RGB or RGBA to Algan's [R, G, B, glow, opacity].
convert_to_uint8
is_transparent
mult_opacity	Return a copy of this color with its opacity scaled.
mult_rgb
new_empty	Return a new opaque black Color on this color's device.
prep_set
set_glow
set_opacity	Return a copy of this color with its opacity replaced.
set_rgb

Attributes

glow
opacity
rgb

static add_defaults(color)

Widen RGB or RGBA to Algan’s [R, G, B, glow, opacity].

Only 3 and 4 channels are widened. A width that is neither is not a color missing its extra channels, and padding it anyway meant the error it eventually caused reported a shape the caller never wrote – ImageMob(torch.zeros(8, 8, 2)) was told its texture had shape (8, 8, 4).

mult_opacity(opacity)

Return a copy of this color with its opacity scaled.

Reach for this when you want “half as visible as it already is” and for masking a texture, where the factor varies per texel. Use set_opacity() when you know the alpha you want.

Unlike set_opacity() this does not range-check, for two reasons. A multiply is a transform rather than a setting, so the same reasoning that keeps scale(0) and a negative scale legal applies. And this is on the per-batch render path – get_render_primitives calls it with texture-sized tensors and with replayed opacity values that an overshooting rate function can carry a hair outside [0, 1] – where an element-wise check would both cost and reject legitimately.

Parameters:

opacity – Factor to multiply the existing alpha by. A tensor is broadcast against this color, giving one factor per row – per vertex or per texel – which is how a mask is applied to a texture.

Returns:

A new color. The color it was called on is left unchanged, so the named palette constants stay safe to reuse.

Return type:

Color

See also

set_opacity()

Replace the alpha outright, range-checked.

new_empty(*args, **kwargs)

Return a new opaque black Color on this color’s device.

Overrides torch.Tensor.new_empty(), which would otherwise hand back an uninitialized tensor of the requested size: a color’s row is always the fixed [R, G, B, glow, opacity], so the size arguments are accepted for signature compatibility and ignored, and the row is zeroed rather than left as whatever the allocator returned. Keyword arguments are forwarded to the Color constructor.

set_opacity(opacity)

Return a copy of this color with its opacity replaced.

Opacity is one of the five channels, so ordinary color arithmetic moves it along with the others – BLUE * 0.5 halves the alpha as well as the brightness, and renders half-transparent. This sets the alpha channel alone and leaves red, green, blue and glow as they are.

Parameters:

opacity – The new opacity, in [0, 1]: 0 is invisible, 1 fully opaque. A value outside that range raises rather than being clamped. A tensor is broadcast against this color, giving one opacity per row – per vertex or per texel, and every element has to be in range.

Returns:

A new color. The color it was called on is left unchanged, so the named palette constants stay safe to reuse.

Return type:

Color

Raises:

AlganConfigurationError – If opacity is non-finite, or outside [0, 1].

See also

mult_opacity()

Scale the existing alpha instead of replacing it.