API Reference

class abspy.VertexGroup(filepath, process=True, quiet=False, refit=True, global_group=False)

Class for manipulating planar primitives.

__init__(self, filepath, process=True, quiet=False, refit=True, global_group=False)

Init VertexGroup. Class for manipulating planar primitives.

Parameters

• filepath (str or Path) – Filepath to vertex group file (.vg) or binary vertex group file (.bvg)

• process (bool) – Immediate processing if set True

• quiet (bool) – Disable logging if set True

• refit (bool) – Refit plane parameters if set True

• global_group (bool) – Remove the first group as an unnecessary global one containing all subgroups if set True

load_file(self)

Load (ascii / binary) vertex group file.

process(self)

Start processing vertex group.

get_points(self, row=1)

Get points from vertex group.

Parameters

row (int) – Row number where points are specified, defaults to 1 for filename.vg

Returns

as_float – Point cloud

Return type

(n, 3) float

get_primitives(self)

Get primitives from vertex group.

Returns

• params ((n, 4) float) – Plane parameters

• bounds ((n, 2, 3) float) – Bounding box of the primitives

• groups ((n, m, 3) float) – Groups of points

• ungrouped_points ((u, 3) float) – Points that belong to no group

• obbs ((n, 4, 3) float) – Oriented bounding box of the primitives

normalise_from_centroid_and_scale(self, centroid, scale, num=None)

Normalising points.

Centroid and scale are provided to be mitigated, which are identical with the return of scale_and_offset() such that the normalised points align with the corresponding mesh. Notice the difference with normalise_points_to_centroid_and_scale().

Parameters

• centroid ((3,) float) – Centroid of the points to be mitigated

• scale (float) – Scale of the points to be mitigated

• num (None or int) – If specified, random sampling is performed to ensure the identical number of points

Returns

None – Normalised (and possibly sampled) self.points

Return type

NoneType

normalise_to_centroid_and_scale(self, centroid=(0, 0, 0), scale=1.0, num=None)

Normalising points to the provided centroid and scale. Notice the difference with normalise_points_from_centroid_and_scale().

Parameters

• centroid ((3,) float) – Desired centroid of the points

• scale (float) – Desired scale of the points

• num (None or int) – If specified, random sampling is performed to ensure the identical number of points

Returns

None – Normalised (and possibly sampled) self.points

Return type

NoneType

fit_plane(points, mode='PCA')

Fit plane parameters for a point set.

Parameters

• points ((n, 3) float) – Points to be fit

• mode (str) – Mode of plane fitting, ‘PCA’ (recommended) or ‘LSA’ (may introduce distortions)

Returns

• param ((4,) float) – Plane parameters, (a, b, c, d) as in a * x + b * y + c * z = -d

• obb ((4,3) float) – Oriented bounding box of the plane

save_vg(self, filepath)

Save vertex group into a vg file.

Parameters

filepath (str or Path) – Filepath to save vg file

save_bvg(self, filepath)

Save vertex group into a bvg file.

Parameters

filepath (str or Path) – Filepath to save vg file

save_planes_txt(self, filepath)

Save plane parameters into a txt file.

Parameters

filepath (str or Path) – Filepath to save txt file

save_planes_npy(self, filepath)

Save plane params into an npy file.

Parameters

filepath (str or Path) – Filepath to save npy file

save_bounds_npy(self, filepath)

Save plane bounds into an npy file.

Parameters

filepath (str or Path) – Filepath to save npy file

class abspy.VertexGroupReference(filepath, num_samples=10000, process=True, quiet=False)

Class of reference vertex group sampled from meshes.

__init__(self, filepath, num_samples=10000, process=True, quiet=False)

Init VertexGroupReference. Class of reference vertex group sampled from meshes.

Parameters

• filepath (str or Path) – Filepath to a mesh

• num_samples (int) – Number of sampled points

• process (bool) – Immediate processing if set True

• quiet (bool) – Disable logging if set True

process(self)

Start processing mesh data.

save_vg(self, filepath)

Save primitives into a vg file.

Parameters

filepath (str or Path) – Filepath to save vg file

save_bvg(self, filepath)

Save primitives into a bvg file.

Parameters

filepath (str or Path) – Filepath to save bvg file

class abspy.CellComplex(planes, bounds, obbs=None, points=None, initial_bound=None, initial_padding=0.1, additional_planes=None, build_graph=False, quiet=False)

Class of cell complex from planar primitive arrangement.

__init__(self, planes, bounds, obbs=None, points=None, initial_bound=None, initial_padding=0.1, additional_planes=None, build_graph=False, quiet=False)

Init CellComplex. Class of cell complex from planar primitive arrangement.

Parameters

• planes ((n, 4) float) – Plana parameters

• bounds ((n, 2, 3) float) – Corresponding bounding box bounds of the planar primitives

• obbs ((n, 4, 3) float) – Corresponding oriented bounds of the planar primitives

• points ((n, ) object of float) – Points grouped into primitives, points[any]: (m, 3)

• initial_bound (None or (2, 3) float) – Initial bound to partition

• build_graph (bool) – Build the cell adjacency graph if set True.

• additional_planes (None or (n, 4) float) – Additional planes to append to the complex, can be missing planes due to occlusion or incapacity of RANSAC

• quiet (bool) – Disable logging and progress bar if set True

refine_planes(self, theta=0.17453333333333335, epsilon=0.005, normalise_normal=False)

Refine planar primitives.

First, compute the angle of the supporting planes for each pair of planar primitives. Then, starting from the pair with the smallest angle, test if the following two conditions are met: (a) the angle between is lower than a threshold. (b) more than a specified number of points lie on both primitives. Merge the two primitives and fit a new plane if the conditions are satisfied.

Parameters

• theta (float) – Angle tolerance, primitive pair has to be less than this tolerance to be refined

• epsilon (float) – Distance tolerance, primitive pair has to be less than this tolerance to be refined

• normalise_normal (bool) – Normalise normal if set True

prioritise_planes(self, prioritise_verticals=True)

Prioritise certain planes to favour building reconstruction.

First, vertical planar primitives are accorded higher priority than horizontal or oblique ones to avoid incomplete partitioning due to missing data about building facades. Second, in the same priority class, planar primitives with larger areas are assigned higher priority than smaller ones, to make the final cell complex as compact as possible. Note that this priority setting is designed exclusively for building models.

Parameters

prioritise_verticals (bool) – Prioritise vertical planes if set True

construct(self, exhaustive=False, num_workers=0)

Construct cell complex.

Two-stage primitive-in-cell predicate. (1) bounding boxes of primitive and existing cells are evaluated for possible intersection. (2), a strict intersection test is performed.

Generated cells are stored in self.cells. * query the bounding box intersection. * optional: intersection test for polygon and edge in each potential cell. * partition the potential cell into two. rewind if partition fails.

Parameters

• exhaustive (bool) – Do exhaustive partitioning if set True

• num_workers (int) – Number of workers for multi-processing, disabled if set 0

visualise(self, indices_cells=None, temp_dir='./')

Visualise the cells using trimesh.

pyglet installation is needed for the visualisation.

Parameters

• indices_cells (None or (n,) int) – Indices of cells to be visualised

• temp_dir (str) – Temp dir to save intermediate visualisation

property num_cells

Number of cells in the complex.

property num_planes

Number of planes in the complex, excluding the initial bounding box.

volumes(self, multiplier=1.0, engine='Qhull')

list of cell volumes.

Parameters

• multiplier (float) – Multiplier to the volume

• engine (str) – Engine to compute volumes, can be ‘Qhull’ or ‘Sage’ with native SageMath

Returns

as_float – Volumes of cells

Return type

list of float

cell_representatives(self, location='center', num=1)

Return representatives of cells in the complex.

Parameters

• location (str) – ‘center’ represents the average of the vertices of the polyhedron, ‘centroid’ represents the center of mass/volume, ‘random_r’ represents random point(s) by rejection, ‘random_t’ represents random point(s) by tetrahedralization, ‘skeleton’ represents skeleton point(s), ‘boundary’ represents boundary point(s) by triangulation

• num (int) – number of samples per cell, only applies to ‘random’ and ‘star’

Returns

as_float – Representatives of cells in the complex.

Return type

(n, 3) float for ‘center’ and ‘centroid’, or (m, n, 3) for ‘random’ and ‘skeleton’ and ‘boundary’

cells_in_mesh(self, filepath_mesh, engine='distance')

Return indices of cells that are inside a reference mesh.

Parameters

• filepath_mesh (str or Path) – Filepath to reference mesh

• engine (str) – Engine to compute predicate, can be ‘embree’ for pyembree (up to x50 faster but not stable), ‘ray_triangle’ for a slower ray tracer, or ‘distance’ for signed distance

Returns

as_int – Indices of cells being inside the reference mesh

Return type

(n, ) int

print_info(self)

Print info to console.

save(self, filepath)

Save the cell complex to a CC file.

Parameters

filepath (str or Path) – Filepath to save CC file, ‘.cc’ suffix recommended

save_npy(self, filepath)

Save the cells to an npy file (deprecated).

Parameters

filepath (str or Path) – Filepath to save npy file

save_obj(self, filepath, indices_cells=None, use_mtl=False)

Save polygon soup of indexed convexes to an obj file.

Parameters

• filepath (str or Path) – Filepath to save obj file

• indices_cells ((n,) int) – Indices of cells to save to file

• use_mtl (bool) – Use mtl attribute in obj if set True

save_plm(self, filepath, indices_cells=None)

Save polygon soup of indexed convexes to a plm file (polyhedron mesh in Mapple).

Parameters

• filepath (str or Path) – Filepath to save plm file

• indices_cells ((n,) int) – Indices of cells to save to file

class abspy.AdjacencyGraph(graph=None, quiet=False)

Class Adjacency graph of the cell complex.

__init__(self, graph=None, quiet=False)

Init AdjacencyGraph.

Parameters

• graph (None or networkx Graph) – Graph object

• quiet (bool) – Disable logging if set True

load_graph(self, filepath)

Load graph from an external file.

Parameters

filepath (str or Path) – Filepath to networkx graph

assign_weights_to_n_links(self, cells, attribute='area_overlap', normalise=True, factor=1.0, engine='Qhull', cache_interfaces=False)

Assign weights to edges between every cell.

Parameters

• cells (list of Polyhedra objects) – Polyhedra cells

• attribute (str) – Attribute to use for encoding n-links, options are ‘radius_overlap’, ‘area_overlap’, ‘vertices_overlap’, ‘area_misalign’ and ‘volume_difference’

• normalise (bool) – Normalise the attribute if set True

• factor (float) – Factor to multiply to the attribute

• engine (str) – Engine to compute convex hull ‘Qhull’ is supported at the moment

• cache_interfaces (bool) – Cache interfaces if set True

assign_weights_to_st_links(self, weights)

Assign weights to edges between each cell and the s-t nodes.

Parameters

weights (dict) – Weights in respect to each node, can be the occupancy probability or the signed distance of the cells.

cut(self)

Perform cutting operation.

Returns

• cut_value (float) – Cost of the cut

• reachable (list of int) – Reachable nodes from the S node

save_surface_obj(self, filepath, cells=None, engine='rendering')

Save the outer surface to an OBJ file, from interfaces between cells being cut.

Parameters

• filepath (str or Path) – Filepath to save obj file

• cells (None or list of Polyhedra objects) – Polyhedra cells

• engine (str) – Engine to extract surface, can be ‘rendering’, ‘sorting’ or ‘projection’

draw(self)

Draw the graph with nodes represented by their UID.

to_indices(self, uids)

Convert UIDs to indices.

Parameters

uids (list of int) – UIDs of nodes

Returns

as_list – Indices of nodes

Return type

list of int

to_dict(self, weights_list)

Convert a weight list to weight dict keyed by self.uid.

Parameters

weights_list (list of) – Weight list

Returns

as_dict – Weight dict

Return type

dict

abspy.attach_to_log(level=20, filepath=None, colors=True, capture_warnings=True)

Attach a stream handler to all loggers.

Parameters

• level (enum (int)) – Logging level, like logging.INFO

• colors (bool) – If True try to use colorlog formatter

• capture_warnings (bool) – If True capture warnings

• filepath (None or str) – path to save the logfile

Returns

logger – Logger attached with a stream handler

Return type

Logger object