mapteksdk.data.filled_polygon module

The filled polygon class.

class Loop(owner, point_indices, edge_indices)

Bases: object

A loop of points in a FilledPolygon.

Do not construct this class directly. Instead access it via the FilledPolygon.loops property.

This allows for accessing the point and edge properties associated with a particular loop of points.

Notes

The properties of this class return copies of the property arrays. This means assigning directly to the values returned from the properties will not mutate the original arrays.

Parameters:

owner (FilledPolygon) –
point_indices (MutableIndexSequence) –
edge_indices (MutableIndexSequence) –

property point_count: int

Count of the points in this loop.

Raises:: StaleDataError – If this loop has been invalidated due to the owning object being closed, or due to a point being deleted.

property edge_count: int

Count of the edges in this loop.

Raises:: StaleDataError – If this loop has been invalidated due to the owning object being closed, or due to a point being deleted.

property points: PointArray

A copy of the points in the loop.

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

property edges: EdgeArray

A copy of the edges in the loop.

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

property point_selection: BooleanArray

A copy of the point selection information for the loop.

Setting this property to a sequence of length self.point_count will set the point selection for the points in this loop without affecting the point selection of points in different loops.

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

property edge_selection: BooleanArray

A copy of the edge selection information for the loop.

Setting this property to a sequence of length self.edge_count will set the edge selection for the edges in this loop without affecting the edge selection of edges in different loops.

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

property point_attributes: MutableMapping[AttributeKey, numpy.ndarray]

Access the point attributes for the loop.

This returns a mapping which allows for basic operations on the point attributes.

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

property edge_attributes: MutableMapping[AttributeKey, numpy.ndarray]

Access the edge attributes for the loop.

This returns a mapping which allows for basic operations on the edge attributes.

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

append_points(points)

Append a point to the end of the current loop.

This updates the edges

Parameters:

point – A single point to append to the loop, or an array of points to append.
points (PointLike | PointArrayLike) –

Raises:

ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

remove_points(point_indices)

Remove one or more points from this loop.

This will invalidate the properties of the FilledPolygon object, requiring values to be re-read from the application. Any unsaved changes will be lost.

Parameters:

point_indices (int | Sequence[int]) – A sequence of point indices to remove, or a single point index to remove. This is based on the index of the point in this loop. i.e. An index of zero indicates the first point in this loop.

Raises:

DegenerateTopologyError – If the remove operation would result in this loop containing less than 3 points.
ObjectClosedError – If the FilledPolygon this loop is a part of is closed.
StaleDataError – If this loop has been invalidated due to the removal of a point.

class FilledPolygon(object_id=None, lock_type=LockType.READWRITE, *, rollback_on_error=False)

Bases: Topology

A filled polygon which can have holes in it.

A FilledPolygon is defined by a series of loops. Each loop is defined as ‘additive’ or ‘subtractive’. The inside of an additive loop are filled, whereas the inside of a subtractive loop are not. Whether a loop is additive or subtractive is defined by the following rules:

The outermost loop is always additive.
Any loop inside of an additive loop is subtractive.
Any loop outside of a subtractive loop is additive.

This means that for each point has edges connecting it to precisely two other points. The filled polygon supports duplicate points, so if a subtractive loop would otherwise share a point with an additive loop, the object will contain duplicate points (i.e. Two different points with the same x, y and z ordinates).

Notes

If two loops overlap, with neither fully contained inside the other, the Python SDK will not issue an error, however, whether either loop is additive or subtractive is not defined.

Examples

Instead of assigning to the points property of a FilledPolygon, the points are added via the add_loop() function. This accepts a list of ordered points representing the loop to add to the object. This is demonstrated by the following script:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import FilledPolygon
>>> with Project() as project, project.new(
...         "cad/example_filled_polygon", FilledPolygon) as filled_polygon:
...     # The outermost loop is additive.
...     filled_polygon.add_loop(
...         [[-10, -10, 0], [10, -10, 0], [10, 10, 0], [-10, 10, 0]]
...     )
...     # This loop is contained within the previous one, which is
...     # additive, so it is subtractive.
...     filled_polygon.add_loop(
...         [[-5, -5, 0], [5, -5, 0], [5, 5, 0], [-5, 5, 0]]
...     )
...     # This loop is contained within the previous one, which is
...     # subtractive, so it is additive.
...     filled_polygon.add_loop(
...         [[-2.5, -2.5, 0], [2.5, -2.5, 0], [2.5, 2.5, 0], [-2.5, 2.5, 0]]
...     )
...     # Set the filled parts of the object to be plum coloured.
...     filled_polygon.fill_colour = [221, 160, 221, 255]

Parameters:

object_id (ObjectID | None) –
lock_type (LockType) –
rollback_on_error (bool) –

property id: ObjectID[FilledPolygon]

Object ID that uniquely references this object in the project.

Returns:: The unique id of this object.
Return type:: ObjectID

classmethod static_type()

Return the type of a topology as stored in a Project.

This can be used for determining if the type of an object is topology.

property loops: Sequence[Loop]

The sequence of loops which define the object.

Raises:: DegenerateTopologyError – If the object is degenerate.

remove_loop(loop_index)

Delete the loop with the specified index.

This deletes all of the points which makes up that loop.

Parameters:

loop_index (int) – The index of the loop to delete in the loops sequence for this object.

Raises:

IndexError – If there is no loop with the give index.
DegenerateTopologyError – If attempting to delete the only loop in the object.

Notes

Calling this function will discard any unsaved changes and invalidate all of the properties for this object.

property points: PointArray

Flat view of the points which make up the FilledPolygon.

This contains all of the points in each loop contained within the filled polygon. Similar to the points properties of other objects, properties with one value per point (e.g. point_selection) have the index based on this array.

property point_count: int

The number of points in the FilledPolygon.

Unlike PointSet and most other objects with points, a FilledPolygon may include duplicate points.

property point_selection: BooleanArray

Point selection array.

This has one value per point in the array. The point at points[i] is selected if point_selection[i] is True.

property point_attributes: PrimitiveAttributes

Access to the custom point attributes.

Each point attribute has one value for each point. Note that unlike most other objects with points, a FilledPolygon can contain duplicate points. These duplicate points can have different values for a point attribute, which can cause issues in certain algorithms.

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

cancel()

Cancel any pending changes to the object.

This undoes all changes made to the object since it was opened (including any changes saved by save()) and then closes the object.

After this is called, attempting to read or edit any of the properties on this object (other than the id) will raise an ObjectClosedError.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing). It is not necessary to call this for a read only object as there will be no pending changes.
ObjectClosedError – If called on a closed object.

close()

Closes the object and saves the changes to the Project.

Attempting to read or edit properties of an object after closing it will raise a ReadOnlyError.

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 coordinate_system: CoordinateSystem | None

The coordinate system the points of this object are in.

If the object has no coordinate system, this will be None.

Raises:: ReadOnlyError – If set on an object open for read-only.

Warning

Setting this property does not change the points. This is only a label stating the coordinate system the points are in.

Examples

Creating an edge network and setting the coordinate system to be WGS84. Note that setting the coordinate system does not change the points. It is only stating which coordinate system the points are in.

>>> from pyproj import CRS
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polygon
>>> project = Project()
>>> with project.new("cad/rectangle", Polygon) as new_edges:
...     # Coordinates are in the form [longitude, latitude]
...     new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]]
...     new_edges.coordinate_system = CRS.from_epsg(4326)

Often a standard map projection is not convenient or accurate for a given application. In such cases a local transform can be provided to allow coordinates to be specified in a more convenient system. The below example defines a local transform where the origin is translated 1.2 degrees north and 2.1 degree east, points are scaled to be twice as far from the horizontal origin and the coordinates are rotated 45 degrees clockwise about the horizontal_origin. Note that the points of the polygon are specified in the coordinate system after the local transform has been applied.

>>> import math
>>> from pyproj import CRS
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polygon, CoordinateSystem, LocalTransform
>>> project = Project()
>>> transform = LocalTransform(
...     horizontal_origin = [1.2, 2.1],
...     horizontal_scale_factor = 2,
...     horizontal_rotation = math.pi / 4)
>>> system = CoordinateSystem(CRS.from_epsg(20249), transform)
>>> with project.new("cad/rectangle_transform", Polygon) as new_edges:
...     new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]]
...     new_edges.coordinate_system = system

See also

mapteksdk.data.coordinate_systems.CoordinateSystem: Allows for a coordinate system to be defined with an optional local transform.

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.

dissociate_raster(raster)

Removes the raster from the object.

If an error occurs after dissociating a raster resulting in save() not being called, the dissociation of the raster can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Dissociating a raster will not be undone if an error occurs.

Parameters:

raster (Raster | ObjectID[Raster]) – The raster to dissociate.

Returns:

True if the raster was successfully dissociated from the object, False if the raster was not associated with the object.

Return type:

bool

Raises:

TypeError – If raster is not a Raster.
ReadOnlyError – If this object is open for read-only.

Notes

This only removes the association between the Raster and the object, it does not clear the registration information from the Raster.

Examples

Dissociate the first raster found on a picked object.

>>> from mapteksdk.project import Project
>>> from mapteksdk import operations
>>> project = Project()
>>> oid = operations.object_pick(
...     support_label="Pick an object to remove a raster from.")
... with project.edit(oid) as data_object:
...     report = f"There were no raster to remove from {oid.path}"
...     for index in data_object.rasters:
...         data_object.dissociate_raster(data_object.rasters[index])
...         report = f"Removed raster {index} from {oid.path}"
...         break
... # Now that the raster is dissociated and the object is closed,
... # the raster can be associated with a different object.
... operations.write_report("Remove Raster", report)

property edges: EdgeArray

The edges which make up the FilledPolygon.

This contains all of the edges of each loop which makes up the filled Polygon. Similar to the edges properties of other objects, properties with one value per edge (e.g. edge_selection) have the index based on this array.

property extent: Extent: The axes aligned bounding extent of the object.

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.

get_colour_map()

Return the ID of the colour map object associated with this object.

Returns:: The ID of the colour map object or null object ID if there is no colour map.
Return type:: ObjectID

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

property rasters: dict[int, ObjectID[Raster]]

The raster associated with this object.

This is a dictionary of raster indices and Object IDs of the raster images currently associated with this object.

The keys are the raster ids and the values are the Object IDs of the associated rasters. Note that all raster ids are integers however they may not be consecutive - for example, an object may have raster ids 0, 1, 5 and 200.

Notes

Rasters with higher indices appear on top of rasters with lower indices. The maximum possible raster id is 255.

Removing a raster from this dictionary will not remove the raster association from the object. Use dissociate_raster to do this.

Examples

Iterate over all rasters on an object and invert the colours. Note that this will fail if there is no object at the path “target” and it will do nothing if no rasters are associated with the target.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for raster in read_object.rasters.values():
...         with project.edit(raster) as edit_raster:
...             edit_raster.pixels[:, :3] = 255 - edit_raster.pixels[:, :3]

remove_coordinate_system()

Remove the coordinate system from the object.

This does not change the geometry of the object. It only clears the label which states what coordinate system the object is in.

This has no effect if the object does not have a coordinate system.

save()

Save the changes made to the object.

Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().

Returns:: The change reasons for the operation. This depends on what changes to the object were saved. If the api_version is less than 1.9, this always returns ChangeReasons.NO_CHANGE.
Return type:: ChangeReasons

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, bool, int, float, str]] | 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.

Notes

If an error occurs after adding a new object attribute or editing an existing object attribute resulting in save() not being called, the changes to the object attributes can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Adding new object attributes, or editing the values of object attributes, will not be undone if an error occurs.

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 edge_count: int: The number of edges in the FilledPolygon.

property edge_selection: BooleanArray

Edge selection array.

This has one value per edge in the array. The point at edges[i] is selected if edge_selection[i] is True.

property edge_attributes: PrimitiveAttributes

Access to the custom edge attributes.

Each edge attribute has one value for each edge.

property fill_colour: Colour

The fill colour of the Polygon.

The colour used to colour the contents of “additive” loops which make up the FilledPolygon object.

point_to_loop(index)

Find the loop which contains the point with the given index.

This is useful for performing an operation on all of the points in the same loop as the point with the given index.

Parameters:: index (int) – Index of the point in the points array to find the loop of. This does not support negative indices.
Returns:: The Loop object which this loop is a part of.
Return type:: Loop
Raises:: IndexError – If there is no point with the specified index.

edge_to_loop(index)

Find the loop which contains the edge with the given index.

This is useful for performing an operation on all of the edges in the same loop as the edge with the given index.

Parameters:: index (int) – Index of the edge in the edges array to find the loop of. This does not support negative indices.
Returns:: The Loop object which this loop is a part of.
Return type:: Loop
Raises:: IndexError – If there is no edge with the specified index.

add_loop(new_points)

Add a new loop to the object.

It is the caller’s responsibility to ensure that the new loop does not overlap with any other loops in the object (including itself). The new edges are automatically derived from the given points.

Parameters:: new_points (PointArrayLike) – The points which define the new loop.
Returns:: The newly added loop.
Return type:: Loop

Examples

The return values of this function can be used to access and set the properties of the newly added points and edges.

>>> filled_polygon: FilledPolygon
>>> loop = filled_polygon.add_loop(
...     [[0, 0, 0], [10, 0, 0], [0, 10, 0]]
... )
>>> # Read the newly added points.
>>> new_points = loop.points
>>> # Read the newly added edges.
>>> new_edges = loop.edges
>>> # Select the newly added points.
>>> loop.point_selection = True
>>> # Select the newly added edges.
>>> loop.edge_selection = True