mapteksdk.data.primitives.facet_properties module

Support for facet primitives.

A facet is a triangle defined by three points. In Python, a facet is represented as a numpy array containing three integers representing the indices of the points which make up the three corners of the triangle. For example, the facet [0, 1, 2] indicates the triangle defined by the 0th, 1st and 2nd points. Because facets are defined based on points, all objects which inherit from FacetProperties must also inherit from PointProperties.

class FacetProperties

Bases: object

Mixin class which provides spatial objects support for facet primitives.

A facet is a triangle drawn between three points. For example, the facet [i, j, k] is the triangle drawn between object.points[i], object.points[j] and object.points[k].

Functions and properties defined on this class are available on all classes which support facets.

is_read_only: bool

property facets: FacetArray

A 2D numpy array of facets in the object.

This is of the form: [[i0, j0, k0], [i1, j1, k1], …, [iN, jN, kN]] where N is the number of facets. Each i, j and k value is the index of the point in Objects.points for the point used to define the facet.

append_facets(*facets)

Append new facets to the end of the facets array.

Using this function is preferable to assigning to the facets array directly because it allows facets to be added to the object without any risk of changing existing facets by accident. The return value can also be used to assign facet properties for the new facets.

Parameters:: facets – New facets to append to the array.
Returns:: Boolean array which can be used to assign properties for the newly added facets.
Return type:: BooleanArray

Examples

This function can be used to add a single facet to an object:

>>> surface: Surface
>>> # Add a facet connecting points 0, 1 and 2.
>>> surface.append_facets([0, 1, 2])

Passing multiple facets can be used to append multiple facets at once:

>>> surface: Surface
>>> # Add a facet between points 0, 1 and 2 and another between points
>>> # 1 and 2 and 3.
>>> surface.append_facets([0, 1, 2], [1, 2, 3])

This function also accepts iterables of facets, so the following is functionally identical to the previous example:

>>> surface: Surface
>>> # Add a facet between points 0, 1 and 2 and another between points
>>> # 1 and 2 and 3.
>>> surface.append_facets([[0, 1, 2], [1, 2, 3]])

The return value of this function can be used to assign facet properties to the newly added facets:

>>> surface: Surface
>>> new_facet_indices = surface.append_facets([0, 1, 2], [1, 2, 3])
>>> # Colour the two new facets blue and magenta.
>>> surface.facet_colours[new_facet_indices] = [
...     [0, 0, 255, 255], [255, 0, 255, 255]]

property facet_colours: ColourArray: A 2D numpy array containing the colours of the facets.

property facet_selection: BooleanArray

A 1D numpy array representing which facets are selected.

If object.facet_selection[i] = True then the ith facet is selected.

property facet_count: int: The number of facets in the object.

remove_facets(facet_indices)

Remove one or more facets from the object.

Calling this function is preferable to altering the facets array because this function also removes the facet properties associated with the removed facets (e.g. facet colours, facet visibility, etc). Additionally, after the removal any points or edges which are not part of a facet will be removed from the object.

This operation is performed directly on the Project and will not be undone if an error occurs.

Parameters:: facet_indices (npt.ArrayLike) – The index of the facet to remove or a list of indices of facets to remove. Indices should only contain 32-bit unsigned integer (They should be greater than or equal to 0 and less than 2**32). Any index greater than or equal to the facet count is ignored. Passing an index less than zero is not supported. It will not delete the last facet.
Returns:: If passed a single facet index, True if the facet was removed and False if it was not removed. If passed an iterable of facet indices, True if the object supports removing facets and False otherwise.
Return type:: bool
Raises:: ReadOnlyError – If called on an object not open for editing. This error indicates an issue with the script and should not be caught.

Warning

Any unsaved changes to the object when this function is called are discarded before any facets are deleted. If you wish to keep these changes, call save() before calling this function.

property facet_attributes: PrimitiveAttributes

Access the custom facet attributes.

These are arrays of values of the same type, with one value for each facet.

Use Object.facet_attributes[attribute_name] to access a facet attribute called attribute_name. See PrimitiveAttributes for valid operations on facet attributes.

Returns:: Access to the facet attributes.
Return type:: PrimitiveAttributes
Raises:: ValueError – If the type of the attribute is not supported.

save_facet_attribute(attribute_name, data)

Create new and/or edit the values of the facet attribute attribute_name.

This is equivalent to Object.facet_attributes[attribute_name] = data.

Saving a facet attribute using an AttributeKey allows for additional metadata to be specified.

Parameters:

attribute_name (str | AttributeKey) – The name or key of the attribute.
data (npt.ArrayLike) – Data for the associated attribute. This should be a ndarray of shape (facet_count,). The ith entry in this array is the value of this primitive attribute for the ith facet.

Raises:

ValueError – If the type of the attribute is not supported.
AmbiguousNameError – If there is already an attribute with the same name, but with different metadata.

delete_facet_attribute(attribute_name)

Delete a facet attribute.

This is equivalent to: facet_attributes.delete_attribute(attribute_name)

Parameters:: attribute_name (str | AttributeKey) – The name or key of the attribute.