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

  • aabbs ((n, 2, 3) float) – Axis-aligned bounding boxes of the primitives

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

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

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

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_aabbs_npy(self, filepath)

Save plane AABBs 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.

perturb(self, sigma)

Perturb plane normals with Gaussian noise.

Parameters:

sigma ((1,) float) – Gaussian noise standard deviation

inject_points(self, points, threshold=0.05, overwrite=True, keep_bottom=False, keep_wall=False, compute_normal=False, pseudo_normal=False, pseudo_size=1)

Inject unordered points to vertex groups.

Parameters:

  • points ((n, 3) float) – Point cloud

  • threshold ((1,) float) – Distance threshold

  • overwrite (bool) – Overwrite sampled points with input points if set True, otherwise append

  • keep_bottom (bool) – Keep sampled points on bottom if set True, effective only when overwrite is True

  • keep_wall (bool) – Keep sampled points on walls if set True, effective only when overwrite is True

  • compute_normal (bool) – Compute normal if set True, otherwise inherit normal from plane parameters

  • pseudo_normal (bool) – Take pseudo points into account for normal estimation if set True, otherwise random normal for them, not implemented

  • pseudo_size ((1,) int) – Minimal group size for pseudo group without injected points, only apply to dangling groups without injected points, effective only when overwrite is True

property bottom_indices

Group indices of bottom facets.

Parameters:

epsilon ((1,) float) – Tolerance for horizontality and minimum Z predicates

Returns:

as_int – Indices of bottom groups

Return type:

(n,) int

property wall_indices

Group indices of wall facets.

Parameters:

epsilon ((1,) float) – Tolerance for verticality predicate

Returns:

as_int – Indices of wall groups

Return type:

(n,) int

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, aabbs, 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, aabbs, 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

  • aabbs ((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 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 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