mapteksdk.data.cells module¶

This module contains data types where their distinguishing feature is the usage of cell primitives.

Currently this only includes the GridSurface class.

class mapteksdk.data.cells.GridSurface(object_id=None, lock_type=<LockType.READWRITE: 2>, major_dimension_count=None, minor_dimension_count=None, x_step=None, y_step=None, start=None, column_major=False)¶

Bases: mapteksdk.data.base.Topology, mapteksdk.data.primitives.point_properties.PointProperties, mapteksdk.data.primitives.cell_properties.CellProperties

A dense irregular cell network. In Eureka these are referred to as grid surfaces. They are generally more compact than Surfaces and calculations can be performed faster on them. However they cannot represent surfaces with disconnected parts and do not allow holes in the surface (except when the surface self-intersects).

The object will contain major_dimension_count * minor_dimension_count points which are used to define the cells. The structure contains (major_dimension_count - 1) * (minor_dimension_count - 1) cells - due to the gridded nature of the object adjacent cells share points. To make working with the gridded data structure easier, this object provides two dimensional versions of the point and cell properties. This allows these properties to be indexed based on the row and column of the cell in the grid.

The cell in the ith row and the jth column is defined as the quadrilateral between cell_points[i][j], cell_points[i + 1][j], cell_points[i + 1][j + 1] and cell_points[i][j + 1] For example, the zeroth cell is between the points cell_points[0][0], cell_points[0][1], cell_points[1][1] and cell_points[1][0]. Cell selection and cell visibility map the selection and visibility to the cells in the same way.

The constructor for grid surface can generate a regular grid (via the x_step and y_step parameters) in the X and Y direction. If this form of the constructor is used then only setting the Z values will create a consistent grid with no self-intersections. Use start to specify the start position of the grid.

Parameters

major_dimension_count (int) – The number of rows used to store the grid surface (Default 1). Note that this will only correspond to the number of rows in the grid surface if the points are stored in row major order. This is ignored if opening an existing irregular grid surface.
minor_dimension_count (int) – The number of columns used to store the grid surface (Default 1). Note that this will only correspond to the number of columns in the grid surface if the points are stored in row major order. This is ignored if opening an existing grid surface.
x_step (int) – If x_step, y_step or start are specified, the constructor will set the points to a regular grid using this as the size of each grid square in the X direction (Default 0). Ignored when opening an existing grid surface. To make scripts run faster, only specify this argument if you intend to use the generated regular grid.
y_step (int) – If x_step, y_step or start are specified, the constructor will set the points to a regular grid using this as the size of each grid square in the Y direction. (Default 0). Ignored when opening an existing grid surface. To make scripts run faster, only specify this argument if you intend to use the generated regular grid.
start (array_like) – If x_step, y_step or start are specified, the constructor will set the points to a regular grid using this as the start point of the generated grid. The default is [0, 0, 0]. Ignored when opening an existing grid surface. To make scripts run faster, only specify this argument if you intend to use the generated regular grid.
column_major (bool) – If False (default) then the generated grid will be in row major order (X values change in rows, Y values in columns). If True the generated grid will be in column major order (Y values change in rows, X values in columns). This has no effect if x_step, y_step and start are not specified. Ignored when opening an existing grid surface.

Warning

GridSurfaces have no protection against self-intersecting cells or cells intersecting each other. This can cause unintuitive index to spatial relationships and holes in the surface.

Raises

ValueError – If major_dimension_count or minor_dimension_count are less than zero.
TypeError – If major_dimension_count or minor_dimension_count are not integers.

Examples

Creates a new grid surface using the grid constructor then sets the Z coordinates to be the sine of the X coordinate plus the Y coordinate. By using the grid constructor then setting only the Z coordinates, this ensures the resulting surface has no self-intersections and an intuitive index to spatial relationship.

>>> import math
>>> import numpy as np
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/sin_x+y", GridSurface(
...         major_dimension_count=8, minor_dimension_count=8,
...         x_step=math.pi/4, y_step=math.pi/4)) as new_grid:
...     np.sin(new_grid.points[:, 1] + new_grid.points[:, 2],
...            out=new_grid.point_z)

If the X and Y information is already available or does not neatly conform to a grid, construction of the object will be faster if the X and Y step parameters are not specified. In the below example the X and Y coordinates are not regularly spaced (as is often the case for real world data) so it is more efficient to not specify the x_step and y_step parameters.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> points = [[1.1, 1.15, 1.11], [1.98, 1.17, 1.08], [3.02, 1.13, 1.07],
...           [1.08, 1.99, 1.07], [2.01, 2.03, 1.37], [3.00, 2.11, 1.33],
...           [1.13, 3.08, 1.08], [2.00, 3.01, 0.99], [3.18, 3.07, 1.34]]
>>> with project.new("surfaces/noisy", GridSurface(
...         major_dimension_count=3, minor_dimension_count=3
...         )) as new_grid:
...     new_grid.points = points

property cell_visibility_2d¶

The visibility of the cells reshaped to be a grid of size major_dimension_count - 1 by minor_dimension_count - 1.

Raises: ValueError – If assigned a value which is not major_dimension_count - 1 by minor_dimension_count - 1.

Examples

Set all cells along the diagonal of the grid surface to be invisible, then print the cell visibility. The loop is bounded by the lower of the major and minor dimension counts, so it will work even for grid surfaces which are not squares.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/cell_visibility", GridSurface(
...         major_dimension_count=5, minor_dimension_count=5,
...         x_step=1, y_step=1)) as new_cells:
...     for i in range(min(new_cells.cell_visibility_2d.shape)):
...         new_cells.cell_visibility_2d[i][i] = False
...     print(new_cells.cell_visibility_2d)
[[False, True, True, True]
 [True, False, True, True]
 [True, True, False, True]
 [True, True, True, False]]

Note that when the object created in the previous example is viewed from above, the resulting cell visibility will be mirrored on the Y axis to what was printed. This is because ascending y will go up the screen, whereas the ascending rows are printed down the screen. i.e. The grid surface will have the following visibility:

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("surfaces/cell_visibility") as read_cells:
...     print(read_cells.cell_visibility_2d[:, ::-1])
[[ True  True  True False]
 [ True  True False  True]
 [ True False  True  True]
 [False  True  True  True]]

Set a 2x2 area of cells to be invisible then print the resulting cell visibility.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/cell_visibility_2", GridSurface(
...         major_dimension_count=5, minor_dimension_count=5,
...         x_step=1, y_step=1)) as new_cells:
...     new_cells.cell_visibility_2d[1:3, 1:3] = [[False, False],
...                                               [False, False]]
[[True, True, True, True]
 [True, False, False, True]
 [True, False, False, True]
 [True, True, True, True]]

property cell_selection_2d¶

The selection of the cells reshaped in a grid of size: major_dimension_count - 1 by minor_dimension_count - 1

Raises: ValueError – If set to a value which is not major_dimension_count - 1 by minor_dimension_count - 1

property cell_points¶

A view of points reshaped to follow the underlying grid structure of the surface. This means that for the cell in row i and column j, the points which define the four corners of the cell are: cell_points[i][j], cell_points[i+1][j], cell_points[i+1, j+1] and cell_points[i][j+1].

As this is a view of the points, any changes made to points will be reflected in cell_points and vice versa.

Raises: ValueError – If there are not exactly major_dimension_count * minor_dimension_count points in the object. This will cause the reshape operation to fail. Calling save() will trim/pad the points to be the correct size.

See also

mapteksdk.data.primitives.PointProperties.points: Flat array access to points.

property cell_point_colours¶

A view of the point_colours reshaped to be major_dimension_count by minor_dimension_count.

See also

mapteksdk.data.primitives.PointProperties.point_colours: Flat array access to point colours.

property cell_point_visibility¶

A view of the point_visibility reshaped to be major_dimension_count by minor_dimension_count.

See also

mapteksdk.data.primitives.PointProperties.point_visibility: Flat array access to point visibility.

property cell_point_selection¶

A view of the point_selection reshaped to be major_dimension_count by minor_dimension_count.

See also

mapteksdk.data.primitives.PointProperties.point_selection: Flat array access to point selection.

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