colour.primitive

colour.primitive(method: Literal['Cube', 'Grid'] | str = 'Cube', **kwargs: Any) → Tuple[NDArray, NDArray, NDArray]

Generate a geometry primitive.

This function creates geometric primitives such as cubes or grids with configurable dimensions and segmentation. The generated primitive includes vertices with position, texture coordinates, normal vectors, and colour data, along with face and outline indexes for rendering.

Parameters:

• method (Literal['Cube', 'Grid'] | str) –

  Generation method for the primitive. Supported methods are:

  • 'Cube': Generate a 3D cube primitive

  • 'Grid': Generate a 2D grid primitive

• axis – {colour.geometry.primitive_grid()}, Axis to which the primitive will be normal, or plane with which the primitive will be co-planar.

• depth – {colour.geometry.primitive_cube()}, Cube depth.

• depth_segments – {colour.geometry.primitive_cube()}, Cube segments count along the depth.

• dtype_indexes – {colour.geometry.primitive_grid(), colour.geometry.primitive_cube()}, numpy.dtype to use for the grid indexes. Defaults to the numpy.dtype defined by the colour.constant.DTYPE_INT_DEFAULT attribute.

• dtype_vertices – {colour.geometry.primitive_grid(), colour.geometry.primitive_cube()}, numpy.dtype to use for the grid vertices. Defaults to the numpy.dtype defined by the colour.constant.DTYPE_FLOAT_DEFAULT attribute.

• height – {colour.geometry.primitive_grid(), colour.geometry.primitive_cube()}, Height of the primitive.

• planes – {colour.geometry.primitive_cube()}, Grid primitives to include in the cube construction.

• width – {colour.geometry.primitive_grid(), colour.geometry.primitive_cube()}, Width of the primitive.

• width_segments – {colour.geometry.primitive_grid(), colour.geometry.primitive_cube()}, Number of segments along the width.

• height_segments – {colour.geometry.primitive_grid(), colour.geometry.primitive_cube()}, Number of segments along the height.

• kwargs (Any)

Returns:

Tuple containing three arrays:

• vertices: Structured array of vertex data including position, texture coordinates, normal vectors, and colour values

• faces: Face indexes for rendering a filled primitive

• outline: Outline indexes for rendering the edges of the primitive

Return type:

tuple

References

[Cab]

Examples

>>> vertices, faces, outline = primitive()
>>> print(vertices)
[([-0.5,  0.5, -0.5], [0., 1.], [-0., -0., -1.], [0., 1., 0., 1.])
 ([ 0.5,  0.5, -0.5], [1., 1.], [-0., -0., -1.], [1., 1., 0., 1.])
 ([-0.5, -0.5, -0.5], [0., 0.], [-0., -0., -1.], [0., 0., 0., 1.])
 ([ 0.5, -0.5, -0.5], [1., 0.], [-0., -0., -1.], [1., 0., 0., 1.])
 ([-0.5,  0.5,  0.5], [0., 1.], [ 0.,  0.,  1.], [0., 1., 1., 1.])
 ([ 0.5,  0.5,  0.5], [1., 1.], [ 0.,  0.,  1.], [1., 1., 1., 1.])
 ([-0.5, -0.5,  0.5], [0., 0.], [ 0.,  0.,  1.], [0., 0., 1., 1.])
 ([ 0.5, -0.5,  0.5], [1., 0.], [ 0.,  0.,  1.], [1., 0., 1., 1.])
 ([ 0.5, -0.5, -0.5], [0., 1.], [-0., -1., -0.], [1., 0., 0., 1.])
 ([ 0.5, -0.5,  0.5], [1., 1.], [-0., -1., -0.], [1., 0., 1., 1.])
 ([-0.5, -0.5, -0.5], [0., 0.], [-0., -1., -0.], [0., 0., 0., 1.])
 ([-0.5, -0.5,  0.5], [1., 0.], [-0., -1., -0.], [0., 0., 1., 1.])
 ([ 0.5,  0.5, -0.5], [0., 1.], [ 0.,  1.,  0.], [1., 1., 0., 1.])
 ([ 0.5,  0.5,  0.5], [1., 1.], [ 0.,  1.,  0.], [1., 1., 1., 1.])
 ([-0.5,  0.5, -0.5], [0., 0.], [ 0.,  1.,  0.], [0., 1., 0., 1.])
 ([-0.5,  0.5,  0.5], [1., 0.], [ 0.,  1.,  0.], [0., 1., 1., 1.])
 ([-0.5, -0.5,  0.5], [0., 1.], [-1., -0., -0.], [0., 0., 1., 1.])
 ([-0.5,  0.5,  0.5], [1., 1.], [-1., -0., -0.], [0., 1., 1., 1.])
 ([-0.5, -0.5, -0.5], [0., 0.], [-1., -0., -0.], [0., 0., 0., 1.])
 ([-0.5,  0.5, -0.5], [1., 0.], [-1., -0., -0.], [0., 1., 0., 1.])
 ([ 0.5, -0.5,  0.5], [0., 1.], [ 1.,  0.,  0.], [1., 0., 1., 1.])
 ([ 0.5,  0.5,  0.5], [1., 1.], [ 1.,  0.,  0.], [1., 1., 1., 1.])
 ([ 0.5, -0.5, -0.5], [0., 0.], [ 1.,  0.,  0.], [1., 0., 0., 1.])
 ([ 0.5,  0.5, -0.5], [1., 0.], [ 1.,  0.,  0.], [1., 1., 0., 1.])]
>>> print(faces)
[[ 1  2  0]
 [ 1  3  2]
 [ 4  6  5]
 [ 6  7  5]
 [ 9 10  8]
 [ 9 11 10]
 [12 14 13]
 [14 15 13]
 [17 18 16]
 [17 19 18]
 [20 22 21]
 [22 23 21]]
>>> print(outline)
[[ 0  2]
 [ 2  3]
 [ 3  1]
 [ 1  0]
 [ 4  6]
 [ 6  7]
 [ 7  5]
 [ 5  4]
 [ 8 10]
 [10 11]
 [11  9]
 [ 9  8]
 [12 14]
 [14 15]
 [15 13]
 [13 12]
 [16 18]
 [18 19]
 [19 17]
 [17 16]
 [20 22]
 [22 23]
 [23 21]
 [21 20]]
>>> vertices, faces, outline = primitive("Grid")
>>> print(vertices)
[([-0.5,  0.5,  0. ], [0., 1.], [0., 0., 1.], [0., 1., 0., 1.])
 ([ 0.5,  0.5,  0. ], [1., 1.], [0., 0., 1.], [1., 1., 0., 1.])
 ([-0.5, -0.5,  0. ], [0., 0.], [0., 0., 1.], [0., 0., 0., 1.])
 ([ 0.5, -0.5,  0. ], [1., 0.], [0., 0., 1.], [1., 0., 0., 1.])]
>>> print(faces)
[[0 2 1]
 [2 3 1]]
>>> print(outline)
[[0 2]
 [2 3]
 [3 1]
 [1 0]]