mapteksdk.data.colourmaps module¶

This module contains data types used to represent colour maps (also known as legends).

A colour map can be used to apply a special colour schema to objects based on their properties (e.g. by attribute or position, etc).

The two types are:

NumericColourMap - Colour based on a numerical value.
StringColourMap - Colour based on a string (letters/words).

class mapteksdk.data.colourmaps.NumericColourMap(object_id=None, lock_type=<LockType.READWRITE: 2>)¶

Bases: mapteksdk.data.base.DataObject

Numeric colour maps map numeric values to a colour. The colours can either be smoothly interpolated or within bands. See below update functions for examples.

Notes

For interpolated colours there must be the same number of colours as intervals.

For solid colour maps there must be n-1 colours where n is intervals.

Tip: The ‘cm’ module in matplotlib can generate compatible colour maps.

Raises: InvalidColourMapError – If on save the ranges array contains less than two values.

See also

mapteksdk.data.primitives.PrimitiveAttributes.set_colour_map: Colour a topology object by a colour map.

Examples

Create a colour map which would colour primitives with a value between 0 and 50 red, between 50 and 100 green and between 100 and 150 blue.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import NumericColourMap
>>> project = Project()
>>> with project.new("legends/colour_map", NumericColourMap) as new_map:
>>>     new_map.ranges = [0, 50, 100, 150]
>>>     new_map.colours = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]
>>>     new_map.interpolated = False

Create a colour map which similar to above, but smoothly transitions from red to green to blue.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import NumericColourMap
>>> project = Project()
>>> with project.new("legends/interpolated_map", NumericColourMap) as new_map:
>>>     new_map.ranges = [0, 75, 150]
>>>     new_map.colours = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]
>>>     new_map.interpolated = True

Colour a surface using a colour map by the “order” point_attribute. This uses the colour map created in the first example so make sure to run that example first.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Surface
>>> points = [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
...           [0.5, 0.5, 0.5], [0.5, 0.5, -0.5]]
>>> facets = [[0, 1, 4], [1, 2, 4], [2, 3, 4], [3, 0, 4],
...           [0, 1, 5], [1, 2, 5], [2, 3, 5], [3, 0, 5]]
... order = [20, 40, 60, 80, 100, 120, 140, 75]
>>> project = Project()
>>> colour_map_id = project.find_object("legends/colour_map")
>>> with project.new("surfaces/ordered_surface", Surface) as surface:
...     surface.points = points
...     surface.facets = facets
...     surface.point_attributes["order"] = order
...     surface.point_attributes.set_colour_map("order", colour_map_id)

Edit the colour map associated with the surface created in the previous example so make sure to run that first.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import NumericColourMap
>>> project = Project()
>>> with project.edit("surfaces/ordered_surface") as my_surface:
>>>   with project.edit(my_surface.get_colour_map()) as cm:
>>>     pass # Edit the colour map here.

classmethod static_type()¶

Return the type of numeric colour maps as stored in a Project.

This can be used for determining if the type of an object is a numeric colour map.

get_properties()¶: Load properties from the Project. This resets all properties back to their state when save() was last called, undoing any changes which have been made.

property interpolated¶: If True, the colour map is saved with interpolated colours between each range. If False, the colour map is saved with solid boundaries.

property intervals¶

Returns the number of intervals in the colour map.

Returns: Number of intervals in the colour map.
Return type: int

Notes

This is the length of the ranges array.

property colours¶

The list of the colours in the colour map. If the colour map contains N colours, this is of the form: [[r1, g1, b1, a1], [r2, g2, b2, a2], …, [rN, gN, bN, aN]].

If interpolated = True, the length of this list (N) should be equal to the length of the ranges list. If interpolated = False, the length of this list (N) should be equal to the length of the ranges list minus one.

Notes

On save, if the colours array is too large, the excess colours are silently discarded.

On save, if the colours array is too small when compared with the ranges array, the behaviour varies: If the colour map is interpolated: - If the size is one too few, the upper limit is appended. - If the size it two too few, the lower limit is prepended and the upper limit is appended. - Otherwise the colours are padded with the last colour in the map.

If the colour map is solid the colours array is padded with the last colour in the map.

property ranges¶

List of numbers used to define where colour transitions occur in the colour map. For example, if ranges = [0, 50, 100] and the colour map is solid, then between 0 and 50 the first colour would be used and between 50 and 100 the second colour would be used.

If the colour map is interpolated, then the first colour would be used at 0 and between 0 and 50 the colour would slowly change to the second colour (reaching the second colour at 50). Then between 50 and 100 the colour would slowly transition from the second colour to the third colour.

Raises

InvalidColourMapError – If set to have fewer than than two values.
ValueError – If set to an array containing a non-numeric value.

Notes

This array dictates the intervals value and also controls the final length of the colours array when saving.

property upper_cutoff¶

Colour to use for values which are above the highest range in the ranges array.

For example, if ranges = [0, 50, 100] then this colour is used for any value greater than 100. The default value is Red ([255, 0, 0])

Notes

Set the alpha value to 0 to make this colour invisible.

property lower_cutoff¶

Colour to use for values which are below the lowest range in the ranges array.

For example, if ranges = [0, 50, 100] then this colour is used for any value lower than 0. The default value is blue ([0, 0, 255, 255]).

Returns: Array of the form [red, green, blue, alpha] defining the colour to use for values which are below the colour map.
Return type: ndarray

Notes

Set the alpha value to 0 to make these items invisible.

save()¶

Saves the changes to the numeric colour map.

Raises

Exception – If the colour map is opened in read only mode.
InvalidColourMapError – If the ranges array contains less than two values.

class mapteksdk.data.colourmaps.StringColourMap(object_id=None, lock_type=<LockType.READWRITE: 2>)¶

Bases: mapteksdk.data.base.DataObject

Colour maps which maps colours to strings rather than numbers.

Parameters

object_id (ObjectID) – id of dataengine object to use. If None then create a new stringColourMap.
lock_type (LockType) – The type of lock to place on the object. Default is read/write.

Raises

InvalidColourMapError – If on save the legends array is empty.

Warning

Colouring objects other than PointSets and DenseBlockModels using string colour maps may not be supported by applications (but may be supported in the future). If it is not supported the object will either be coloured red or the viewer will crash when attempting to view the object.

Notes

The indices of these values are related to the colours given for the same indices and the arrays must have the same number of elements.

Set value for a (alpha) to 0 to make out of bounds items invisible.

Examples

Create a string colour map which maps “Gold” to yellow, “Silver” to grey and “Iron” to red.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import StringColourMap
>>> project = Project()
>>> with project.new("legends/map", StringColourMap) as new_map:
>>>     new_map.legend = ["Gold", "Silver", "Iron"]
>>>     new_map.colours = [[255, 255, 0], [100, 100, 100], [255, 0, 0]]

classmethod static_type()¶

Return the type of string colour maps as stored in a Project.

This can be used for determining if the type of an object is a string colour map.

get_properties()¶: Load properties from the Project. This resets all properties back to their state when save() was last called, undoing any changes which have been made.

property intervals¶: Returns the number of intervals in the colour map. This is the length of the legend array.

property legend¶

1D numpy array of string values defining a legend that matches the colours array.

The string colour_map.legend[i] is mapped to colour_map.colours[i].

Raises

TypeError – If set to an array which does not contain only strings.
InvalidColourMapError – If set to an array with zero elements.

Notes

There must be no duplicates to avoid exceptions. The number of elements must match the colours array.

property colours¶

The list of colours in the colour map.

Notes

Must be the same number of elements as the legend array and/or as indicated by the intervals attribute.

On save, if the colours list is larger than the legend list it will be trimmed to the length of the legend. If the colours list is shorter than the legends list it will be padded with green ([0, 255, 0, 255]).

property cutoff¶

The colour to use for values which don’t match any value in legends.

Notes

Set the alpha value to 0 to make these items invisible.

Default is red: [255, 0, 0, 255]

Examples

If the legend = [“Gold”, “Silver”] then this property defines the colour to use for values which are not in the legend (ie: anything which is not “Gold” or “Silver”). For example, it would define what colour to represent ‘Iron’ or ‘Emerald’.

save()¶

Saves the changes to the string colour map.

Raises

CannotSaveInReadOnlyModeError – If the colour map is opened in read only mode.
InvalidColourMapError – If the legends array is empty.