Session

class Session(quiet=False)

Bases: object

Headless workspace that holds geometry data and dispatches operations.

Attributes:

dataDataContainer

Container for point cloud geometries.

modelsDataContainer

Container for fitted mesh/model geometries.

Methods

Session.apply(operation_name, geometries, ...)	Apply a GeometryOperations function.
Session.filter(geometries, prop_name[, ...])	Filter geometries by property value range.
Session.group(geometries, name)	Assign geometries to a named group.
Session.list_filtered([type, name, group, ...])	Return matching geometries as (index, geometry) pairs.
Session.load_session(filepath[, persist])	Restore session state from a session file.
Session.log_command(cmd_str)	Append a command string to the session log.
Session.measure(property_name, geometries, ...)	Compute a property via GeometryProperties.
Session.merge(geometries[, name])	Merge multiple geometries into one.
Session.open(filepath[, offset, scale, ...])	Load geometries from a file.
Session.remove(geometries)	Remove geometries from the session.
Session.resolve(spec)	Resolve a target specifier to a list of Geometry objects.
Session.resolve_many(specs)	Resolve multiple specifiers, preserving order and deduplicating.
Session.save(geometries, filepath, **kwargs)	Export geometries to a file.
Session.save_session(filepath[, sections])	Save session state to filepath.
Session.ungroup(geometries)	Remove geometries from their groups.

apply(operation_name, geometries, **kwargs)

Apply a GeometryOperations function.

Parameters:

operation_namestr

Registered operation name (e.g. "cluster").

geometrieslist of Geometry

Target geometries.

**kwargs

Operation-specific parameters. Use workers=N to control the number of parallel worker processes.

Special flags (consumed before dispatching):

• persist (bool, default True): when False, results are stored in _last_results but NOT added to session containers (transient, only available via @last).

Returns:

list of Geometry

Newly created geometries.

filter(geometries, prop_name, lower=None, upper=None, **kwargs)

Filter geometries by property value range.

Automatically detects whether the property yields per-vertex arrays (point-level filtering) or scalars (population-level filtering).

Parameters:

geometrieslist of Geometry

Target geometries.

prop_namestr

Vertex property name or measure name.

lowerfloat, optional

Lower bound (inclusive).

upperfloat, optional

Upper bound (inclusive).

**kwargs

Additional parameters passed to property computation.

Returns:

tuple of (int, int, str)

(kept, removed, level) where level is "point" or "population".

group(geometries, name)

Assign geometries to a named group.

Parameters:

geometrieslist of Geometry

Geometries to group.

namestr

Display name for the group.

Returns:

str

UUID of the created or updated group.

list_filtered(type=None, name=None, group=None, visible=None)

Return matching geometries as (index, geometry) pairs.

Parameters:

typestr, optional

Filter by geometry type (cluster, mesh, parametric).

namestr, optional

Filter by geometry name. Supports glob patterns (e.g. 0*) and case-insensitive substring matching.

groupstr, optional

Filter by group name. Supports glob patterns and substring matching.

visiblebool, optional

Filter by visibility state. When True, only visible geometries are returned; when False, only hidden ones.

Returns:

list of (int, Geometry)

Matching (global_index, geometry) pairs.

load_session(filepath, persist=True)

Restore session state from a session file.

Handles both .pickle and indexed .mosaic formats.

Parameters:

filepathstr

Path to the session file.

persistbool, optional

When True (default), replace the current session state. When False, geometries are only available via @last.

log_command(cmd_str)

Append a command string to the session log.

measure(property_name, geometries, **kwargs)

Compute a property via GeometryProperties.

Parameters:

property_namestr

Property name (e.g. "mesh_area").

geometrieslist of Geometry

Target geometries.

**kwargs

Property-specific parameters.

• output (str, optional): export results to a CSV file.

• store (bool, default False): store per-vertex array results as vertex properties on each geometry.

Returns:

list

One result per input geometry.

merge(geometries, name=None)

Merge multiple geometries into one.

Parameters:

geometrieslist of Geometry

Geometries to merge. All must belong to the same container (data or models).

namestr, optional

Name for the merged geometry. Defaults to the name of the first input geometry.

Returns:

Geometry

The newly created merged geometry.

open(filepath, offset=0, scale=None, sampling_rate=None, persist=True, segmentation=False, **kwargs)

Load geometries from a file.

Parameters:

filepathstr

Path to the input file.

offsetfloat or array-like, optional

Coordinate offset subtracted from scaled vertices as vertices * scale - offset (default 0).

scalefloat or array-like, optional

Scale factor applied to raw vertices. Defaults to the file’s native sampling rate, which converts voxel-index vertices returned by volume loaders into physical units.

sampling_ratefloat, optional

Override the file’s native sampling rate.

persistbool, optional

When True (default), add geometries to session containers. When False, geometries are only available via @last.

segmentationbool, optional

When True, treat the volume as a segmentation and extract surface meshes via VTK’s FlyingEdges3D.

**kwargs

Additional arguments passed to open_file().

Returns:

list of int

Global indices of the newly added geometries.

remove(geometries)

Remove geometries from the session.

Parameters:

geometrieslist of Geometry

Geometries to remove.

Returns:

int

Number of geometries removed.

resolve(spec)

Resolve a target specifier to a list of Geometry objects.

Parameters:

specstr

"#N" for a single geometry, "#N-M" for a range, "*" for every geometry, or "@last" for the results of the most recent open() or apply() call.

Returns:

list of Geometry

resolve_many(specs)

Resolve multiple specifiers, preserving order and deduplicating.

save(geometries, filepath, **kwargs)

Export geometries to a file.

Parameters:

geometrieslist of Geometry

Geometries to export.

filepathstr

Output file path.

**kwargs

Additional export parameters (format, sampling, etc.).

save_session(filepath, sections=None)

Save session state to filepath.

Parameters:

filepathstr

Destination file path.

sectionsdict, optional

Extra sections to include in the file, mapping section names to (encoding, data) tuples (e.g. {"thumbnail": ("png", bytes)}). Ignored for .pickle files.

ungroup(geometries)

Remove geometries from their groups.

Parameters:

geometrieslist of Geometry

Geometries to ungroup.

Returns:

int

Number of geometries ungrouped.