mapteksdk.pointstudio.operations module

This module provides access to operations available in PointStudio.

exception mapteksdk.pointstudio.operations.TooOldForOperation(minimum_version, current_version)

Bases: Exception

Error raised when you attempt to use an operation that isn’t supported by the current version of the application.

class mapteksdk.pointstudio.operations.DistanceMeasurementTarget(value)

Bases: enum.Enum

If there are multiple objects to measure the distance to this specifies how it should be done.

CLOSEST_OBJECT = 1
AVERAGE = 2
class mapteksdk.pointstudio.operations.DistanceType(value)

Bases: enum.Enum

Specifies whether distances should be considered as a signed or absolute.

SIGNED = 1
ABSOLUTE = 2
class mapteksdk.pointstudio.operations.TriangulationOutput(value)

Bases: enum.Enum

Specifies what the output of a triangulation should be.

SINGLE_SURFACE = 1
SURFACE_PER_OBJECT = 2
SPLIT_ALONG_EDGE_CONSTRAINTS = 3
RELIMIT_TO_POLYGON = 4
class mapteksdk.pointstudio.operations.MaskOperation(value)

Bases: enum.Enum

Specifies how an operation should act with existing data.

This is typically used for filtering operations.

AND = 1
OR = 2
REPLACE = 3
format_to_operation_string()

Format the value as expected by an operation input.

mapteksdk.pointstudio.operations.colour_by_distance_from_object(objects_to_colour, base_objects, measurement_target, distance_type, legend)

Colour points based on their (signed) distance from a base or reference objects.

This is useful for comparing triangulations of as-built surfaces against design models to highlight nonconformance. It can also be used to visualise areas of change between scans of the same area, for example a slow moving failure in an open pit mine.

Parameters

  • objects_to_colour (list) – The list of objects to colour.

  • base_objects (list) – The list of base or reference objects to measure the distance from.

  • measurement_target (DistanceMeasurementTarget) – If CLOSEST_OBJECT then colouring is based on the closest base object to that point. If AVERAGE then colour is based on the average distance to every base object.

  • distance_type (DistanceType) – If SIGNED then colouring will depend on which side of the base objects it is on. If ABSOLUTE then colouring will depend on the absolute distance.

  • legend (ObjectID) – A numeric 1D colour map to use as the legend for colouring the object.

mapteksdk.pointstudio.operations.contour_surface(surfaces, lower_limit, upper_limit, major_contour_intervals=15.0, major_contour_colour=(0, 255, 255, 255), minor_contour_intervals=None, minor_contour_colour=(255, 0, 127, 255), destination_path=None)

Create contours from surfaces (triangulations), which are then saved into an edge network object.

Parameters

  • surfaces (list) – The list of surfaces to contour.

  • lower_limit (float) – The minimum value of the contours (the lowest elevation).

  • upper_limit (float) – The maximum value of the contours (the highest elevation).

  • major_contour_intervals (float) – The difference in elevation between major contour lines.

  • major_contour_colour (sequence) – The colour of the major contour lines. This may be a RGB colour [red, green, blue] or a RGBA colour [red, green, blue, alpha].

  • minor_contour_intervals (float or None) – If None then no minor contours lines will be included. The difference in elevation between minor contour lines between the major contour lines.

  • minor_contour_colour (sequence) – The colour of the minor contour lines. This may be a RGB colour [red, green, blue] or a RGBA colour [red, green, blue, alpha]. This is only relevant if minor_contour_intervals is not None.

  • destination_path (str) – The path to where the contours should be written. If None then the default path will be used.

Returns

The list of edge networks created that contain the resulting the contour lines if there are no minor contour lines. Otherwise a list of containers each containing the set of major and minor contour lines will be provided.

Return type

list

Raises

  • ValueError – If a colour cannot be converted to a valid RGBA colour.

  • ValueError – If lower_limit is greater than upper_limit. You may have simply passed the arguments in the wrong way around.

mapteksdk.pointstudio.operations.fill_holes(surfaces)

Fills holes that may appear when editing a surface (triangulation).

Parameters

surfaces (list) – The list of surfaces to have holes filled in.

mapteksdk.pointstudio.operations.filter_by_polygon(scans, polygon, extrusion_direction=(0, 0, 1), keep_points_inside=True, filter_combination=<MaskOperation.AND: 1>)

Filter scan data specified by a polygon and retain points inside or outside the polygon.

Parameters

  • scans (list) – The list of scans to which the filter should be applied.

  • polygon (ObjectID) – The polygons by which to filter

  • extrusion_direction (list of three floats) – The direction of the polygon extrusions.

  • keep_points_inside (bool) – If true then points inside the polygon region are kept, otherwise points outside the polygon region are kept.

  • filter_combination (MaskOperation) – Specify how to combine this filter with any filter previously applied to the selected data.

Raises

ValueError – If extrusion_direction is not a three dimensional vector.

mapteksdk.pointstudio.operations.filter_isolated_points(scans, point_separation, filter_combination=<MaskOperation.AND: 1>)

Filter point that are a large distance from any other points. This can be useful for filtering dust particles or insects that may have been scanned.

Parameters

  • scans (list) – The list of scans to which the filter should be applied.

  • point_separation (float) – Points without a neighbouring point within this distance will be filtered. Any points separated by less than this distance will be retained. This distance should be in metres.

  • filter_combination (MaskOperation) – Specify how to combine this filter with any filter previously applied to the selected data.

mapteksdk.pointstudio.operations.filter_minimum_separation(scans, minimum_distance, filter_combination=<MaskOperation.AND: 1>, treat_scans_separately=False)

Filter point sets to give a more even distribution. Point density decreases as the distance from the scanner increases, so this option is able to reduce the number of points close to the scanner whilst retaining points further away.

Data reduction can have a major impact on the number of points in an object and on the modelling processes.

Parameters

  • scans (list) – The list of scans to which the filter should be applied.

  • minimum_distance (float) – The average minimum separation between points in the object. This distance should be in metres.

  • filter_combination (MaskOperation) – Specify how to combine this filter with any filter previously applied to the selected data.

  • treat_scans_separately (bool) – Treat scans separately such that each scan is considered in isolation. Otherwise it works on all objects as a complete set which results in an even distribution of data for the entire set of objects.

mapteksdk.pointstudio.operations.filter_topography(scans, search_cell_size, keep_lower_points=True, filter_combination=<MaskOperation.AND: 1>, treat_scans_separately=False)

Filter point sets to remove unwanted features. This enables equipment such as trucks and loaders to be filtered and retains only the relevant topographic surface of the mine.

The topography filter divides the scan data into a horizontal grid with a defined cell size. Only the single lowest or highest point in the cell is retained.

Data reduction can have a major impact on the number of points in an object and on the modelling processes.

Parameters

  • scans (list) – The list of scans to which the filter should be applied.

  • search_cell_size (float) – The size of the cells. A typical cell size is between 0.5 and 2 metres. If the cell size is too large it will have the effect of rounding edges.

  • keep_lower_points (bool) – If true then lower points are kept, otherwise the upper points are kept. Upper points would only be used in an underground situation to retain the roof.

  • filter_combination (MaskOperation) – Specify how to combine this filter with any filter previously applied to the selected data.

  • treat_scans_separately (bool) – Treat scans separately such that each scan is considered in isolation. Otherwise it works on all objects as a complete set which results in an even distribution of data for the entire set of objects.

mapteksdk.pointstudio.operations.simplify_by_distance_error(surfaces, distance_error, preserve_boundary_edges=False, avoid_intersections=True)

Simplifies a facet network, reducing the number of facets while maintaining the surface shape.

Triangulation simplification can introduce inconsistencies in the surface, such as triangles that overlap or cross.

Parameters

  • surfaces (list) – The list of surfaces to simplify.

  • distance_error (float) – The maximum allowable average error by which each simplified surface can deviate from its original surface.

  • preserve_boundary_edges (bool) – Specify if the surface boundary should remain unchanged.

  • avoid_intersections (bool) – Prevent self intersections in the resulting surface. This will offer some performance benefit at the cost that the resulting surface may not work with other tools until the self intersections are fixed.

Returns

The list of surfaces.

Return type

list

mapteksdk.pointstudio.operations.simplify_by_triangle_count(surfaces, triangle_count, preserve_boundary_edges=False, avoid_intersections=True)

Simplifies a facet network, reducing the number of facets while maintaining the surface shape.

This should be used if there there is a specific number of triangles to which the triangulation must be restricted.

Triangulation simplification can introduce inconsistencies in the surface, such as triangles that overlap or cross.

Parameters

  • surfaces (list) – The list of surfaces to simplify.

  • triangle_count (int) – The target number of triangles is the approximate number of triangles each simplified triangulation (surface) will contain.

  • preserve_boundary_edges (bool) – Specify if the surface boundary should remain unchanged.

  • avoid_intersections (bool) – Prevent self intersections in the resulting surface. This will offer some performance benefit at the cost that the resulting surface may not work with other tools until the self intersections are fixed.

Returns

The list of surfaces.

Return type

list

mapteksdk.pointstudio.operations.despike(surfaces)

Remove spikes from a triangulation.

The Despike option removes spikes caused by dust or vegetation that may appear when creating a data model. This modifies the objects in-place, i.e it does not create a copy of the data.

If unwanted points remain after running the despike tool, these must be manually deleted or a supplementary tool may resolve the issues.

Parameters

surfaces (list) – The list of surfaces to despike.

Returns

The list of surfaces.

Return type

list

mapteksdk.pointstudio.operations.fix_surface(surfaces)

Automates fixing of common issues with surfaces (triangulation).

The fixes it performs are: - Self intersections - Fixes cases where the surface intersects itself

  • Trifurcations - Fixes cases where the surface touches itself, creating a T-junction.

  • Facet normals - Orient facet normals to point in the same direction. This will be up for surfaces/topography and out for solids.

  • Vertical facets - Remove vertical facets and close the hole this produces by moving the points along the bottom of the vertical region up or the points along the top down, adding points as necessary to neighbouring non-vertical facets to maintain a consistent surface.

Parameters

surfaces (list) – The list of surfaces to fix.

Returns

The list of surfaces.

Return type

list

mapteksdk.pointstudio.operations.topographic_triangulation(scans, trim_edges_to_maximum_length=None, output_option=<TriangulationOutput.SINGLE_SURFACE: 1>, relimit_to_polygon=None, edge_constraints=None, destination='')

Create triangulations (surfaces) of a group of scans.

This works in the XY plane, that is, it triangulates straight down. This means that if there are areas of undercut walls, these will not be modelled accurately.

This option is typically used once scans have been registered and filtered.

Parameters

  • scans (list) – The list of scan objects to triangulate.

  • trim_edges_to_maximum_length (float or None) – If not None, then long, incorrectly generated boundary triangles will be eliminated. A maximum length is specified, which prevents triangles greater than this being created. This option is only applicable to boundary triangles; large voids in the centre of the data will still be modelled.

  • output_option (TriangulationOutput) – If SINGLE_SURFACE, then this creates a single surface from the selected objects/scans. If SURFACE_PER_OBJECT, then this creates a single surface for each selected object/scan. If SPLIT_ALONG_EDGE_CONSTRAINTS, then splits the triangulation into separate objects based on any lines or polygons provided by edge_constraints.

  • relimit_to_polygon (ObjectID or None) – Constrains the model to a polygon, for example a pit boundary. The output_option must be RELIMIT_TO_POLYGON to use this.

  • edge_constraints (list or None) – The lines and polygons to use when splitting the triangulation into separate objects. The output_option must be SPLIT_ALONG_EDGE_CONSTRAINTS to use this.

  • destination (str) – An optional path to the container to store the resulting triangulations. The empty string will use a default path.

mapteksdk.pointstudio.operations.write_report(label, message)

Write a report to the report window of the application.

Parameters

  • label (str) – The label to show on the report.

  • message (str) – The message to include in the report. This is essentially the body of the report itself.

Example

Write out a simple report

>>> from mapteksdk.project import Project
>>> import mapteksdk.pointstudio.operations as studio_operations
>>> project = Project()
>>> studio_operations.write_report(
>>>     'My Script', 'Completed filtering in 1.5 seconds')