API Reference#

Generated from the meshkit package and the type stub of its native extension, meshkit/_meshkit.pyi.

__version__#

The package version, for example "0.2.0".

Meshing#

run(request, *, raster=None, provider_identity='', progress=None, poll_interval=0.1)[source]#

Run in a native worker; deliver bounded progress batches on the caller thread.

Inputs accept native float64 (N,2) buffers or point rows. Result arrays are owned, read-only strided buffers. NumPy is optional: np.asarray(view) shares storage. Polling/cancellation never call Python from a native inner loop.

Any exception raised while waiting, including KeyboardInterrupt and exceptions from progress, cancels the job before it propagates.

Parameters:
  • request (dict) – The job description; see The request.

  • raster (dict, optional) – Terrain grid; see Terrain.

  • provider_identity (str) – Identity of the terrain dataset and version, copied into the report.

  • progress (callable, optional) – Called on the calling thread with each progress event; see Progress events.

  • poll_interval (float) – Seconds between progress polls (at least 0.001).

Returns:

The finished mesh. A refused job returns empty geometry; check result.report["status"].

Return type:

MeshResult

Raises:

ValueError – The request or raster is invalid.

start(request, raster=None, provider_identity='')#

Validate a request, copy it into native storage and start a meshing job.

The request and raster are read and copied before the function returns, so later changes to the caller’s objects do not affect the job. Use meshkit.run() to wait with progress callbacks.

Parameters:
  • request (Mapping[str, Any]) – The job description: source points, paths and options. See The request.

  • raster (Mapping[str, Any] | None) – Optional terrain grid; see Terrain. Without it the job has no terrain provider and terrain tolerances cannot be certified.

  • provider_identity (str) – Caller-supplied identity of the terrain dataset and version, copied into the report. MeshKit does not compute or check it.

Returns:

The running job.

Return type:

Job

Raises:

ValueError – The request or raster is invalid.

class Job#

A meshing job running on a native worker thread; returned by meshkit.start().

The worker runs without the GIL and never calls Python. Deleting the job requests cancellation without waiting; the worker stops at its next cancellation check. The type is not exported by the extension; obtain jobs from meshkit.start().

cancel()#

Request cancellation; a running job stops at its next check with status cancelled.

Return type:

None

property done: bool#

True once the worker has finished, successfully or not.

poll()#

Drain the progress events queued since the last call; see Progress events.

Return type:

list[dict[str, Any]]

result(timeout=-1.0, /)#

Wait for the job and return its mesh.

Parameters:

timeout (float) – Seconds to wait; negative (the default) waits until the job is done. Positional only.

Returns:

The mesh and report. A refused or cancelled job returns empty geometry with the reason in MeshResult.report; it does not raise.

Return type:

MeshResult

Raises:
  • TimeoutError – The job is still running after timeout seconds.

  • RuntimeError – The native worker failed unexpectedly.

Results#

class MeshResult#

A mesh and its report: returned by Job.result() and meshkit.read().

Array attributes are read-only memoryview objects over the native arrays. Each access returns a new view that keeps the native storage alive, also after the result object is deleted. Views with a cell or edge stride are not C-contiguous: numpy.asarray() shares them as strided arrays, and numpy.array(view, copy=True) makes an editable copy. Asking for a contiguous or writable buffer raises BufferError.

A result whose report status is infeasible, cancelled, resource_limit or failed has empty geometry and mappings.

property alias_ids: memoryview#

int64, shape (A,).

Type:

Source ID of each alias

property alias_markers: memoryview#

int32, shape (A,).

Type:

Source marker of each alias

property alias_vertices: memoryview#

uint32, shape (A,).

An alias records a source point that coincided exactly with another one and so shares its vertex.

Type:

Vertex of each source alias

property cell_ids: memoryview#

int64, shape (M,).

Empty when the IDs are the implicit one-based sequence.

Type:

External cell IDs

property cell_types: memoryview#

uint8, shape (M,), 3 or 4. Strided by cell.

Type:

Corner count of each cell

property cells: memoryview#

uint32, shape (M, 4), zero-based, counter-clockwise.

Triangles use the first three slots; the fourth is unused. Strided by cell.

Type:

Cell connectivity

property edge_markers: memoryview#

int32, shape (E,). Strided by edge.

Type:

Marker of each stored edge

property edges: memoryview#

uint32 vertex pairs, shape (E, 2). Strided by edge.

Type:

Edges stored with the mesh

property input_mapping: memoryview#

uint32, shape (P,).

Filled for job results when the retain_input_mapping option is on (the default); empty for meshes read from files.

Type:

Output vertex of each request point

property labels: list[dict[str, Any]]#

rows with id (int) and name (str).

Type:

Region labels

property metadata: dict[str, Any]#

Units and descriptive metadata.

Keys horizontal_metres_per_unit, vertical_metres_per_unit (float), units_known (bool), crs and description (str).

property paths: list[dict[str, Any]]#

Constraint paths carried by the mesh.

Each row has vertices (uint32 memoryview), id (int), marker (int), closed (bool) and kind ("outer", "hole", "region" or "line").

property regions: memoryview#

int32, shape (M,). Strided by cell.

Type:

Region of each cell

property report: dict[str, Any]#

The job or read report, a new dict on each access.

Holds status, complete, counts, conflicts, planning decisions, bounded examples and the resolved options; see Reports.

property vertex_ids: memoryview#

int64, shape (N,).

Empty when the IDs are the implicit one-based sequence.

Type:

External vertex IDs

property vertex_markers: memoryview#

int32, shape (N,). Empty means every marker is zero.

Type:

Vertex markers

property vertices: memoryview#

float64, shape (N, 3) (X, Y, Z).

Type:

Vertex coordinates

Source preparation#

prepare_sources(features, options=None)#

Simplify source polylines and rings, then audit the result independently.

Shared stretches of features are simplified once under the strictest of their owners’ policies. Coordinates never move: simplification only removes vertices. Pass the result to meshkit.prepared_request() to build a job request. See Preparing source geometry.

Parameters:
Returns:

{"ok": False, "error": str} when simplification or its audit fails; otherwise ok (True), points (float64 (N, 2)), point_elevations (float64 (N,), NaN where no height was given), features (one row per input feature) and shared_chains (int).

Return type:

dict

Raises:

ValueError – A feature is invalid, or features that share a point give it different heights.

prepared_request(prepared, *, options=None, metadata=None, **extra)[source]#

Build a request from an audited source graph without per-vertex Python rows.

Parameters:
  • prepared (dict) – A successful result of prepare_sources().

  • options (dict, optional) – Job options; see Options.

  • metadata (dict, optional) – Units and descriptive metadata; see The request.

  • **extra – Further request keys, such as quad_regions, size_field or labels.

Returns:

A request for start() or run() that uses the prepared points, heights and paths.

Return type:

dict

Raises:

ValueError – prepared reports a failure.

Files#

read(path, options=None)#

Read a mesh file.

A .mkb extension selects the lossless MeshKit binary format; any other extension is read as SMS 2DM. A failed read returns no partial mesh: the report holds the reason.

Parameters:
Returns:

The mesh, with an empty MeshResult.input_mapping.

Return type:

MeshResult

Raises:

ValueError – The path contains a NUL character or an option is invalid.

write(path, mesh, options=None)#

Write a mesh atomically as .mkb or .2dm.

The file is written to a temporary in the destination folder and published only when complete. An existing file is kept unless overwrite is true, and a 2DM write refuses to drop attributes the format cannot hold unless allow_attribute_loss is true; both refusals return a report whose complete is false.

Parameters:
Returns:

Report with status, code, message, complete, seconds, work, vertices, triangles, quads, bytes (bytes written) and losses (attribute categories dropped by an allowed lossy 2DM write).

Return type:

dict

Raises:

Build information#

capabilities()#

Describe this build.

Returns:

qt_free, triangles, automatic_mixed and native_raster (all True), license ("Apache-2.0") and version.

Return type:

dict