pygfx.materials.LineMaterial

class pygfx.materials.LineMaterial(thickness=2.0, thickness_space='screen', *, color=(1, 1, 1, 1), color_mode='auto', map=None, maprange=None, dash_pattern=(), dash_offset=0, loop=False, aa=False, **kwargs)

Bases: Material

Basic line material.

Parameters:

  • thickness (float) – The line thickness expressed in logical pixels. Default 2.0.

  • thickness_space (str | CoordSpace) – The coordinate space in which the thickness is expressed (‘screen’, ‘world’, ‘model’). Default ‘screen’.

  • color (Color) – The uniform color of the line (used depending on the color_mode).

  • color_mode (str | ColorMode) – The mode by which the line is coloured. Default ‘auto’.

  • map (TextureMap | Texture) – The texture map specifying the color for each texture coordinate. Optional.

  • maprange (tuple) – The range of the geometry.texcoords that is projected onto the (color) map. Default (0, 1).

  • dash_pattern (tuple) – The pattern of the dash, e.g. [2, 3]. See dash_pattern docs for details. Defaults to an empty tuple, i.e. no dashing.

  • dash_offset (float) – The offset into the dash phase. Default 0.0.

  • loop (bool) – Whether the line’s end should be connected. Default False.

  • aa (bool) – Whether the line is anti-aliased in the shader. Default False.

  • kwargs (Any) – Additional kwargs will be passed to the material base class.

property color

The uniform color of the line.

property aa

Whether the line’s edges are anti-aliased.

Aliasing gives prettier results by producing semi-transparent fragments at the edges. Lines thinner than one physical pixel are also diminished by making them more transparent.

However, because semi-transparent fragments are introduced, artifacts may occur if certain cases. For the same reason, aa only works for the “blended” and “weighted” alpha methods.

Note that by default, pygfx already uses SSAA and/or PPAA to anti-alias the total renderered result. Line-based aa is an additional visual improvement.

property color_mode

The way that color is applied to the line.

See pygfx.utils.enums.ColorMode:

property thickness

The line thickness.

The interpretation depends on thickness_space. By default it is in logical pixels, but it can also be in world or model coordinates.

property thickness_space

The coordinate space in which the thickness (and dash_pattern) are expressed.

See pygfx.utils.enums.CoordSpace:

property map

The texture map specifying the color for each texture coordinate.

Can be None. The dimensionality of the map can be 1D, 2D or 3D, but should match the number of columns in the geometry’s texcoords.

property maprange

The range of the geometry.texcoords that is projected onto the (color) map.

By default this value is (0.0, 1.0), but if the texcoords represents some domain-specific value, e.g. temperature, then maprange can be set to e.g. (0, 100).

property dash_pattern

The dash pattern.

A sequence of floats describing the length of strokes and gaps. The length of the sequence must be an even number. Setting to None or the empty tuple means no dashing.

For example, (5, 2, 1, 2) describes a a stroke of 5 units, a gap of 2, then a short stroke of 1, and another gap of 2. Units are relative to the line thickness (and therefore thickness_space also applies to the dash_pattern).

property dash_offset

The offset into the dash cycle to start drawing at, i.e. the phase.

property loop: bool

Whether the line’s ends should be connected.

If set to True, the end of the line is connected to its beginning, in such a way there is no overlap (which would otherwise be visible for semi-transparent lines). When the line consists of multiple pieces separated by nan-positions, each line-piece is considered a loop.