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.

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.interpolated = False
>>>     new_map.ranges = [0, 50, 100, 150]
>>>     new_map.colours = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]

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.interpolated = True
>>>     new_map.ranges = [0, 75, 150]
>>>     new_map.colours = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]

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.

Return type: int

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: bool

If the colour map is interpolated.

True by default. If you intend to set this to False, you should do so before assigning to the ranges and colours.

For an interpolated colour map, there is one colour for each range value.

For a solid colour map (interpolated=False), there is one less colour than ranges.

property intervals: int

Returns the number of intervals in the colour map.

Notes

This is the length of the ranges array.

property colour_count: int

The number of colours in the map.

If the colour map is interpolated, there must be one colour for each range value.

If the colour map is solid, there is one less colour than there are range values.

property colours: ndarray

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 array should be equal to the length of the ranges array. If interpolated = False, the length of this array should be equal to the length of the ranges array minus one.

Raises: RuntimeError – If set to None.

property ranges: ndarray

The boundaries of the colour map.

Array 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 two values.
UnsortedRangesError – If ranges is not sorted.
ValueError – If set to an array containing a non-numeric value.
RuntimeError – If set to None.

Notes

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

property upper_cutoff: ndarray

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

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, 255])

Notes

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

property lower_cutoff: ndarray

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

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

Notes

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

save()

Saves the changes to the numeric colour map.

Raises

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

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 closed: bool

If this object has been closed.

Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.

Examples

If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.

>>> with self.project.new("cad/point_set", PointSet) as point_set:
>>>     point_set.points = [[1, 2, 3], [4, 5, 6]]
>>>     print("closed?", point_set.closed)
>>> print("closed?", point_set.closed)
closed? False
closed? True

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 is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

property lock_type: LockType

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

Use the is_read_only property instead for checking if an object is open for reading or editing.

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 (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – 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 (Any) – 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.
ValueError – If name starts or ends with whitespace or is empty.
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.

Parameters

object_id (ObjectID) –
lock_type (LockType) –

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 in the viewer or the application will crash when attempting to view the object.

Notes

Given index i, the key colour_map.legend[i] has colour colour_map.colour[i].

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_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:
...    # Sets gold_colour to the colour corresponding to the "Gold"
...    # key in the colour map.
...    # (This will raise a KeyError if "Gold" is not part of the map.)
...    gold_colour = read_map["Gold"]
...    # Sets stone_in_map to True if the key "Stone" is in the colour
...    # map, otherwise it sets it to False.
...    # This is more typically used in if statements e.g.
...    # if "Stone" in read_map
...    stone_in_map = "Stone" in read_map
...    # This will delete the "Iron" key and its associated colour
...    # from the colour map.
...    del read_map["Iron"]

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.

Return type: int

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 closed: bool

If this object has been closed.

Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.

Examples

If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.

>>> with self.project.new("cad/point_set", PointSet) as point_set:
>>>     point_set.points = [[1, 2, 3], [4, 5, 6]]
>>>     print("closed?", point_set.closed)
>>> print("closed?", point_set.closed)
closed? False
closed? True

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 is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

property lock_type: LockType

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

Use the is_read_only property instead for checking if an object is open for reading or editing.

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 (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – 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 (Any) – 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.
ValueError – If name starts or ends with whitespace or is empty.
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

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: int

Returns the number of intervals in the colour map.

This is the length of the legend array.

property legend: ndarray

The string keys of the colour map.

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

Raises

InvalidColourMapError – If set to an array with zero elements.
RuntimeError – If set to None.

Notes

This must not contain duplicates.

property colours: ndarray

The colours in the colour map.

Raises: RuntimeError – If set to None.

Notes

This must have the same number of elements as the legend array.

property cutoff: ndarray

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.

The 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 (i.e. anything which is not “Gold” or “Silver”). For example, it would define what colour to represent ‘Iron’ or ‘Emerald’.

property case_sensitive: bool

If the colour map is case sensitive.

This is True (i.e. case sensitive) by default. When constructing a case-insensitive colour map it is preferable to set this to False before adding any keys. That will allow errors to be detected earlier and more accurately.

Warning

If case_sensitive=False, this class will consider two keys to be the same if they are the same when converted to uppercase using str.upper(). This is stricter than the condition used in Vulcan GeologyCore 2022.1 (and older applications) which consider two keys to be the same if they are the same after uppercasing every english letter, ignoring non-english letters.

Notes

When connected to Vulcan GeologyCore 2022.1 (and older versions) colour maps are assumed to always be case sensitive, regardless of the configuration in the application and saving the colour map will cause it to be set to case sensitive.

Examples

A case sensitive colour map treats keys with different casing as different keys. For example, the colour map creating in the below example contains three keys “iron”, “Iron” and “IRON” each of which has a different colour.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import StringColourMap
>>> if __name__ == "__main__":
...   with Project() as project:
...     with project.new("legends/sensitive_map", StringColourMap
...         ) as string_map:
...       # It is best to set case sensitive before adding any keys
...       # to the colour map.
...       string_map.case_sensitive = True
...       string_map["iron"] = [255, 0, 0, 255]
...       string_map["Iron"] = [0, 255, 0, 255]
...       string_map["IRON"] = [0, 0, 255, 255]
...       for key in string_map.legend:
...         print(key, ":", ",".join(str(x) for x in string_map[key]))
iron : 255,0,0,255
Iron : 0,255,0,255
IRON : 0,0,255,255

The following example is the same except that the colour map is case insensitive. This causes “iron”, “Iron” and “IRON” to be considered the same key, thus each assignment overwrites the previous one resulting in the colour map containing a single key with the last value assigned to it:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import StringColourMap
>>> if __name__ == "__main__":
...   with Project() as project:
...     with project.new("legends/insensitive_map", StringColourMap
...         ) as string_map:
...       # It is best to set case sensitive before adding any keys
...       # to the colour map.
...       string_map.case_sensitive = False
...       string_map["iron"] = [255, 0, 0, 255]
...       string_map["Iron"] = [0, 255, 0, 255]
...       string_map["IRON"] = [0, 0, 255, 255]
...       for key in string_map.legend:
...         print(key, ":", ",".join(str(x) for x in string_map[key]))
iron : 0,0,255,255

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.

ColourMap

Union containing all objects which are colour maps.

alias of Union[StringColourMap, NumericColourMap]