mapteksdk.data.base module
The base classes of all objects in a Project.
The basic unit of data in a Project is an object. All objects in a Project are subclasses of DataObject and thus can access the properties and functions defined by DataObject.
Objects which are intended to be visualised, such as Surface, Polyline or Polygon, inherit from the Topology class.
Objects which are not intended to be visualised on their own, such as colour maps and rasters, inherit directly from the DataObject class.
For objects which contain other objects, see mapteksdk.data.containers.
- ObjectAttributeTypes
Alias for the union of valid ctypes types for object attributes.
alias of
Union
[None
,Type
[None
],c_bool
,c_byte
,c_ubyte
,c_short
,c_ushort
,c_long
,c_ulong
,c_longlong
,c_ulonglong
,c_float
,c_double
,c_char_p
,datetime
,date
]
- ObjectAttributeTypesWithAlias
Object attribute types plus Python types which alias common types.
For convenience some functions treat certain Python types as aliases for C types. The aliases are displayed in the following tables.
Python type
C type
bool
ctypes.c_bool
str
ctypes.c_char_p
int
ctypes.c_int16
float
ctypes.c_double
Notes
The above table only applies for object-level attributes.
alias of
Union
[None
,Type
[None
],c_bool
,c_byte
,c_ubyte
,c_short
,c_ushort
,c_long
,c_ulong
,c_longlong
,c_ulonglong
,c_float
,c_double
,c_char_p
,datetime
,date
,bool
,str
,int
,float
]
- ObjectAttributeDataTypes
Alias for the union of valid data types for object attributes.
alias of
Union
[None
,Type
[None
],Type
[c_bool
],Type
[c_byte
],Type
[c_ubyte
],Type
[c_short
],Type
[c_ushort
],Type
[c_long
],Type
[c_ulong
],Type
[c_longlong
],Type
[c_ulonglong
],Type
[c_float
],Type
[c_double
],Type
[c_char_p
],Type
[datetime
],Type
[date
]]
- exception AlreadyOpenedError
Bases:
RuntimeError
Error raised when attempting to open an object multiple times.
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class Extent(minimum, maximum)
Bases:
object
A multidimensional, axially-aligned “intervals” or “extents”.
This extent is bound to a volume in 3D space.
This is also known as a Axis-Aligned Bounding Box (AABB).
- Parameters
minimum (tuple[float, float, float]) –
maximum (tuple[float, float, float]) –
- minimum
Point representing minimum values in the form [x, y, z].
- maximum
Point representing maximum values in the form [x, y, z].
- property centre: tuple[float, float, float]
Returns the center of the extent.
- Returns
Point representing the center of the extent.
- Return type
point
- property length: float
The length is the maximum of the X, Y or Z dimension.
- Returns
Maximum width of the extent.
- Return type
float
- property span: tuple[float, float, float]
The span of the extent in each direction.
- as_numpy()
Returns the extent as a numpy array.
- Returns
The extent representing as a numpy array.
- Return type
np.array
- overlaps(other)
Return True if this extent and the other overlap.
The extents overlap if they share space which includes if:
They extend over each other and partially cover the same space.
One extent overlaps another by being inside of the other.
The two extents come into contact with one another at a single point.
The two extents come into contact with one another along a line.
The two extents come into contact in a two dimensional rectangular area, similar to two boxes placed next to each other. No part of either extent is inside of the other extent, but both extents are touching.
- Parameters
other (Extent) – The extent to check if it overlaps with this extent.
- Return type
bool
- class DataObject(object_id, lock_type, *, rollback_on_error=False)
Bases:
object
The basic unit of data in a Project.
Each object can be referenced (opened/loaded) from its ID, see ObjectID, Project.read() and Project.edit().
- Parameters
object_id (ObjectID) –
lock_type (LockType) –
rollback_on_error (bool) –
- classmethod static_type()
Return this type as stored in a Project.
- property id: ObjectID[DataObject]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- 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 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
- 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
- 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: str, dtype: Type[date], data: datetime.date | tuple[float])
- set_attribute(name: str, dtype: Type[datetime], data: datetime.datetime | str)
- set_attribute(name: str, dtype: Union[None, Type[None], Type[c_bool], Type[c_byte], Type[c_ubyte], Type[c_short], Type[c_ushort], Type[c_long], Type[c_ulong], Type[c_longlong], Type[c_ulonglong], Type[c_float], Type[c_double], Type[c_char_p], Type[datetime], Type[date]], data: Union[None, Type[None], c_bool, c_byte, c_ubyte, c_short, c_ushort, c_long, c_ulong, c_longlong, c_ulonglong, c_float, c_double, c_char_p, datetime, date, bool, str, int, float])
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.
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
- 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))
- 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.
- 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.
- class Topology(object_id, lock_type, *, rollback_on_error=False)
Bases:
DataObject
Base class for “geometric objects” in a Project.
This object is best thought of as the union of the following:
An arrangement of topological “primitives” including their location in space (known as their geometry).
The connectivity relationships between them (known as their topology).
The properties applied to them.
A given geometric object may contain any number of any of the six basic primitives: points, edges, facets (triangles), tetras (4 sided polyhedra), cells (quadrilaterals) and blocks (cubes or rectangular boxes). However, derived classes typically enforce constraints on the type and number of each primitive allowed in objects of their type. For example an edge chain will have points and edges but not facets.
- Parameters
object_id (ObjectID) –
lock_type (LockType) –
rollback_on_error (bool) –
- 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.
- 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.
- 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().
- 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
- 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))
- 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 id: ObjectID[DataObject]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- 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]
- 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 coordinate_system: mapteksdk.data.coordinate_systems.CoordinateSystem | None
The coordinate system the points of this object are in.
- 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.
Notes
If the object has no coordinate system, this will be None.
Changes are done directly in the project and will not be undone if an error occurs.
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.
- dissociate_raster(raster)
Removes the raster from the object.
This is done directly on the Project and 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)