Facet

A facet is a primitive defined by three points. A facet in the SDK does not store the actual points, but instead references the three points by their index in the points property array. Thus a single facet is represented by an array of three point indices.

Accessing an Object’s Facets

The facets of any object are stored in its facets property. Because most facet-based objects contain multiple facets, the facets property is represented as a NumPy array. Each element of the array represents a facet, which in turn is an array of the three point indices defining the facet.

A Surface is the simplest facet-based spatial object. We can use it to illustrate how to store facets with the example below.

from mapteksdk.project import Project
from mapteksdk.data import Surface
 
project = Project()
 
with project.new("surfaces/cube", Surface) as new_surface:
  new_surface.points = [[-1, -1, -1], [1, -1, -1], [1, 1, -1], [-1, 1, -1],
                        [-1, -1, 1], [1, -1, 1], [1, 1, 1], [-1, 1, 1]]
  new_surface.facets = [[0, 1, 2], [2, 0, 3], # The bottom face.
                        [4, 5, 6], [6, 4, 7], # The top face.
                        [0, 1, 5], [5, 4, 0], # The front face.
                        [1, 2, 5], [5, 6, 2], # The right face.
                        [2, 3, 7], [7, 6, 2], # The back face.
                        [0, 3, 7], [4, 7, 0]] # The left face.

Manipulating an Object’s Facets

Use the following properties and methods to manipulate the facets of an object:

Name	Description
`facet_colours`	Use this property to change the colour of a facet. The colour of each facet is represented by an array containing four values [R, G, B, A] where: R, G and B are each values between 0 and 255. A is a value between 0 and 255 where 0 represents full transparency and 255 represents no transparency.
`facet_count`	Use this property to count the total number of facets within an object. For example, you may want to preallocate NumPy arrays to the correct length. In this case, using `facet_count` is advised for performance reasons with very large objects.
`remove_facets(facet_indices, update_immediately)`	Use this method to remove facets from an object. Specify the facets you want to remove by using the argument `facet_indices` which can be in the form of an integer or an array of integers. Specify if you want the changes to be made immediately to the object by using the boolean argument `update_immediately`. This argument is often set to `False` for large datasets.
`facet_attributes`	Use this method to save or return custom facet attributes in an object. To set a particular edge attribute, you can use the notation `facet_attributes[attribute_name] = data`.
`save_facet_attribute(attribute_name, data)`	Use this method to save a facet attribute and allocate data to it.
`delete_facet_attribute(attribute_name)`	Use this method to delete a facet attribute.

You can read more about the Facet primitive class in the class references.