Colour: colorspace conversion & colour operators

Pure-Python port of BOSL2’s color.scad – the HSL/HSV -> RGB conversions, the rainbow() helper, and the colour operators added onto Bosl2Solid via the Colorable mixin. Each operator resolves to the native PythonSCAD calls: color(), highlight() (the # modifier) and background() (the % / ghost modifier):

cuboid([20, 20, 10]).color("red")
cuboid([20, 20, 10]).hsv(210, 0.8, 0.9)          # colour from an HSV hue
cuboid([20, 20, 10]).color([0.2, 0.5, 0.9, 0.4]) # RGBA
part.highlight()                                  # # debug modifier
part.ghost()                                      # % transparent, non-interacting

hsl() / hsv() are pinned to the real BOSL2 output in tests/test_bosl2_reorient.py.

Because the toolkit builds native geometry rather than a BOSL2 $color attachment tree, recolor() and color_this() both apply the colour directly – an object’s already-coloured children keep their colour (OpenSCAD color() semantics), and there is no $color scheme to revert to, so a "default" colour is a no-op.

Coverage of BOSL2 color.scad

BOSL2 function

Status

Notes

hsl / hsv

ported

hsl() / hsv() – the function form (RGB or RGBA) and the module form as the hsl() / hsv() object methods.

recolor / color_this

ported

object methods; both apply the colour natively (no $color attachment tree in this backend, so they are equivalent).

rainbow

ported

rainbow() colours a list of objects; rainbow_colors() returns the RGB list for a given count.

highlight / highlight_this

ported

highlight() – the # modifier (native highlight()); the single-level highlight_this collapses to the same call.

ghost / ghost_this

ported

ghost() – the % modifier (native background()).

color_overlaps

not ported

a debug module that intersects every pair of children; niche – build it explicitly with the CSG operators if needed.

Examples

A stack of blocks, each a different hue from HSV:

blocks = [s3.cuboid([20, 20, 4]).up(i * 5).hsv(i * 40, 0.8, 0.95) for i in range(5)]
reduce(lambda a, b: a | b, blocks).show()

⬇ Download STL mesh

Rainbow-colouring a list of parts to tell them apart:

parts = [s3.cyl(height=20, radius=4).right(i * 12) for i in range(6)]
reduce(lambda a, b: a | b, rainbow(parts)).show()

⬇ Download STL mesh

API reference

bosl2.color.hsl(height, s=1.0, length=0.5, a=None)[source]

Convert HSL to an [R, G, B] colour (or [R, G, B, A] if a is given) – BOSL2 hsl().

Parameters:

  • height (float) – hue in degrees (0=red, 60=yellow, 120=green, 180=cyan, 240=blue, 300=magenta)

  • s (float) – saturation 0..1 (0 = grey, 1 = vivid). Default 1

  • length (float) – lightness 0..1 (0 = black, 0.5 = bright, 1 = white). Default 0.5

  • a (float | None) – optional alpha 0..1; when given the result is [R, G, B, A]

Returns:

[R, G, B] (each 0..1), or [R, G, B, A] when a is given.

Return type:

list[float]

bosl2.color.hsv(height, s=1.0, v=1.0, a=None)[source]

Convert HSV to an [R, G, B] colour (or [R, G, B, A] if a is given) – BOSL2 hsv().

Parameters:

  • height (float) – hue in degrees (0=red, 60=yellow, 120=green, 180=cyan, 240=blue, 300=magenta)

  • s (float) – saturation 0..1 (0 = grey, 1 = vivid). Default 1

  • v (float) – value 0..1 (0 = black, 1 = bright). Default 1

  • a (float | None) – optional alpha 0..1; when given the result is [R, G, B, A]

Returns:

[R, G, B] (each 0..1), or [R, G, B, A] when a is given.

Return type:

list[float]

bosl2.color.rainbow(items, stride=1, maxhues=None, shuffle=False, seed=None)[source]

Colour each object in items a different hue, returning the coloured list (BOSL2 rainbow()).

Each item must support .color([r, g, b]) (a Bosl2Solid or a native solid). Useful for telling apart the parts of a multi-piece model or debugging a list of paths.

Parameters:

  • items (Sequence) – the objects to colour

  • stride (int) – consecutive colours stride this many steps around the wheel

  • maxhues (int | None) – cap the number of distinct hues (default: len(items))

  • shuffle (bool) – shuffle the hue order

  • seed – seed for the shuffle

Return type:

list

bosl2.color.rainbow_colors(sides, stride=1, maxhues=None, shuffle=False, seed=None)[source]

The list of sides [R, G, B] colours stepped around the ROYGBIV wheel (BOSL2 rainbow()).

Parameters:

  • sides (int) – how many colours to generate

  • stride (int) – consecutive colours stride this many steps around the wheel

  • maxhues (int | None) – cap the number of distinct hues (default: sides)

  • shuffle (bool) – shuffle the hue order

  • seed – seed for the shuffle

Return type:

list[list[float]]

class bosl2.color.Colorable[source]

Bases: ABC

Mixin adding the color.scad colour operators as methods.

Inherited by Bosl2Solid. Every operator resolves to the host’s native colour primitives, which the host provides as _color_native (PythonSCAD color()), _highlight_native (the # modifier) and _ghost_native (the % modifier). Because the toolkit builds native geometry rather than a BOSL2 $color attachment tree, recolor() and color_this() both apply the colour directly (an object’s already-coloured children keep their colour, matching OpenSCAD’s color() semantics).

color(c=None, alpha=None)[source]

Colour this object. c is a name ("red"), [R, G, B], or [R, G, B, A].

Parameters:

alpha (float | None)

recolor(c='default', alpha=None)[source]

Set the colour of this object and its uncoloured descendants (BOSL2 recolor()).

"default" / None leaves the colour unchanged (there is no $color scheme to revert to in the native backend).

Parameters:

alpha (float | None)

color_this(c='default', alpha=None)[source]

Colour just this object (BOSL2 color_this()); equivalent to color() in the native backend, where there is no $color attachment tree to preserve separately.

Parameters:

alpha (float | None)

hsl(height, s=1.0, length=0.5, a=None)[source]

Colour this object from an HSL hue/saturation/lightness (BOSL2 hsl()).

Parameters:

  • height (float)

  • s (float)

  • length (float)

  • a (float | None)

hsv(height, s=1.0, v=1.0, a=None)[source]

Colour this object from an HSV hue/saturation/value (BOSL2 hsv()).

Parameters:

  • height (float)

  • s (float)

  • v (float)

  • a (float | None)

highlight(highlight=True)[source]

Apply the # debug modifier (BOSL2 highlight()); False leaves it unmodified.

Parameters:

highlight (bool)

ghost(ghost=True)[source]

Apply the % (transparent, non-interacting) modifier (BOSL2 ghost()); False leaves it unmodified.

Parameters:

ghost (bool)