mapteksdk.data.colourmaps module

Colour map data types.

Colour maps (also known as legends) can be used to apply a colour schema to other objects based on their properties (e.g. by primitive attribute, position, etc).

The two supported types are:

  • NumericColourMap - Colour based on a numerical value.

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

exception UnsortedRangesError

Bases: InvalidColourMapError

Error raised when the ranges of a colour map are not sorted.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class NumericColourMap(object_id=None, lock_type=LockType.READWRITE)

Bases: 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 id: ObjectID[NumericColourMap]

Object ID that uniquely references this object in the project.

Returns

The unique id of this object.

Return type

ObjectID

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

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
attribute_names()

Returns a list containing the names of all object-level attributes. Use this to iterate over the object attributes.

Returns

List containing the attribute names.

Return type

list

Examples

Iterate over all object attributes of the object stared at “target” and print their values.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for name in read_object.attribute_names():
...         print(name, ":", read_object.get_attribute(name))
close()

Closes the object.

This should be called as soon as you are finished working with an object. To avoid needing to remember to call this function, open the object using a with block and project.read(), project.new() or project.edit(). Those functions automatically call this function at the end of the with block.

A closed object cannot be used for further reading or writing. The ID of a closed object may be queried and this can then be used to re-open the object.

property created_date: datetime

The date and time (in UTC) of when this object was created.

Returns

The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.

Return type

datetime.datetime

delete_all_attributes()

Delete all object attributes attached to an object.

This only deletes object attributes and has no effect on PrimitiveAttributes.

Raises

RuntimeError – If all attributes cannot be deleted.

delete_attribute(attribute)

Deletes a single object-level attribute.

Deleting a non-existent object attribute will not raise an error.

Parameters

attribute (str) – Name of attribute to delete.

Returns

True if the object attribute existed and was deleted; False if the object attribute did not exist.

Return type

bool

Raises

RuntimeError – If the attribute cannot be deleted.

get_attribute(name)

Returns the value for the attribute with the specified name.

Parameters

name (str) – The name of the object attribute to get the value for.

Returns

The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).

Return type

ObjectAttributeTypes

Raises

KeyError – If there is no object attribute called name.

Warning

In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.

get_attribute_type(name)

Returns the type of the attribute with the specified name.

Parameters

name (str) – Name of the attribute whose type should be returned.

Returns

The type of the object attribute name.

Return type

ObjectAttributeDataTypes

Raises

KeyError – If there is no object attribute called name.

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

Returns

The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.

Return type

LockType

property modified_date: datetime

The date and time (in UTC) of when this object was last modified.

Returns

The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.

Return type

datetime.datetime

set_attribute(name, dtype, data)

Sets the value for the object attribute with the specified name.

This will overwrite any existing attribute with the specified name.

Parameters

  • name – The name of the object attribute for which the value should be set.

  • dtype – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.

  • data – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises

  • ValueError – If dtype is an unsupported type.

  • TypeError – If value is an inappropriate type for object attribute name.

  • RuntimeError – If a different error occurs.

Warning

Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
0
class StringColourMap(object_id=None, lock_type=LockType.READWRITE)

Bases: DataObject

Colour maps which maps colours to strings rather than numbers.

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.

The keys are case sensitive - “Unknown” and “unknown” are not considered to be the same key.

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]]

Create the same colour map by treating the colour map as a dictionary.

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

Read colours from the colour map as if it was a dictionary.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("legends/map_dict") as read_map:
...    # Get the colour associated with the key "Gold".
...    # (Will raise a KeyError if "Gold" is not part of the map.)
...    _ = read_map["Gold"]
...    # Determine if a key is part of a map.
...    _ = "Stone" in read_map
...    # Delete a key from the colour map.
...    del read_map["Iron"]
attribute_names()

Returns a list containing the names of all object-level attributes. Use this to iterate over the object attributes.

Returns

List containing the attribute names.

Return type

list

Examples

Iterate over all object attributes of the object stared at “target” and print their values.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for name in read_object.attribute_names():
...         print(name, ":", read_object.get_attribute(name))
close()

Closes the object.

This should be called as soon as you are finished working with an object. To avoid needing to remember to call this function, open the object using a with block and project.read(), project.new() or project.edit(). Those functions automatically call this function at the end of the with block.

A closed object cannot be used for further reading or writing. The ID of a closed object may be queried and this can then be used to re-open the object.

property created_date: datetime

The date and time (in UTC) of when this object was created.

Returns

The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.

Return type

datetime.datetime

delete_all_attributes()

Delete all object attributes attached to an object.

This only deletes object attributes and has no effect on PrimitiveAttributes.

Raises

RuntimeError – If all attributes cannot be deleted.

delete_attribute(attribute)

Deletes a single object-level attribute.

Deleting a non-existent object attribute will not raise an error.

Parameters

attribute (str) – Name of attribute to delete.

Returns

True if the object attribute existed and was deleted; False if the object attribute did not exist.

Return type

bool

Raises

RuntimeError – If the attribute cannot be deleted.

get_attribute(name)

Returns the value for the attribute with the specified name.

Parameters

name (str) – The name of the object attribute to get the value for.

Returns

The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).

Return type

ObjectAttributeTypes

Raises

KeyError – If there is no object attribute called name.

Warning

In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.

get_attribute_type(name)

Returns the type of the attribute with the specified name.

Parameters

name (str) – Name of the attribute whose type should be returned.

Returns

The type of the object attribute name.

Return type

ObjectAttributeDataTypes

Raises

KeyError – If there is no object attribute called name.

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

Returns

The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.

Return type

LockType

property modified_date: datetime

The date and time (in UTC) of when this object was last modified.

Returns

The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.

Return type

datetime.datetime

set_attribute(name, dtype, data)

Sets the value for the object attribute with the specified name.

This will overwrite any existing attribute with the specified name.

Parameters

  • name – The name of the object attribute for which the value should be set.

  • dtype – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.

  • data – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises

  • ValueError – If dtype is an unsupported type.

  • TypeError – If value is an inappropriate type for object attribute name.

  • RuntimeError – If a different error occurs.

Warning

Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
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 id: ObjectID[StringColourMap]

Object ID that uniquely references this object in the project.

Returns

The unique id of this object.

Return type

ObjectID

get(key)

Get the colour associated with the specified key.

If the key is not part of the colour map, cutoff colour will be returned.

Parameters

key (str) – The key to get the associated colour for.

Returns

Numpy array of shape (4,) representing the colour for the specified key.

Return type

numpy.ndarray

Raises

  • TypeError – If the key is not a string.

  • InvalidColourMapError – If the legend and colours arrays have a different number of elements.

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
ColourMap

Union containing all objects which are colour maps.

alias of Union[StringColourMap, NumericColourMap]