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
KeyboardInterruptand exceptions fromprogress, cancels the job before it propagates.- Parameters:
request (dict) – The job description; see The request.
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:
- 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:
- 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
- poll()#
Drain the progress events queued since the last call; see Progress events.
- 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:
- Raises:
TimeoutError – The job is still running after
timeoutseconds.RuntimeError – The native worker failed unexpectedly.
Results#
- class MeshResult#
A mesh and its report: returned by
Job.result()andmeshkit.read().Array attributes are read-only
memoryviewobjects 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, andnumpy.array(view, copy=True)makes an editable copy. Asking for a contiguous or writable buffer raisesBufferError.A result whose report status is
infeasible,cancelled,resource_limitorfailedhas 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_mappingoption is on (the default); empty for meshes read from files.- Type:
Output vertex of each request point
- property metadata: dict[str, Any]#
Units and descriptive metadata.
Keys
horizontal_metres_per_unit,vertical_metres_per_unit(float),units_known(bool),crsanddescription(str).
- property paths: list[dict[str, Any]]#
Constraint paths carried by the mesh.
Each row has
vertices(uint32memoryview),id(int),marker(int),closed(bool) andkind("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
dicton 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; otherwiseok(True),points(float64(N, 2)),point_elevations(float64(N,), NaN where no height was given),features(one row per input feature) andshared_chains(int).- Return type:
- 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().metadata (dict, optional) – Units and descriptive metadata; see The request.
**extra – Further request keys, such as
quad_regions,size_fieldorlabels.
- Returns:
A request for
start()orrun()that uses the prepared points, heights and paths.- Return type:
- Raises:
ValueError –
preparedreports a failure.
Files#
- read(path, options=None)#
Read a mesh file.
A
.mkbextension 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:
- Raises:
ValueError – The path contains a NUL character or an option is invalid.
- write(path, mesh, options=None)#
Write a mesh atomically as
.mkbor.2dm.The file is written to a temporary in the destination folder and published only when complete. An existing file is kept unless
overwriteis true, and a 2DM write refuses to drop attributes the format cannot hold unlessallow_attribute_lossis true; both refusals return a report whosecompleteis false.- Parameters:
- Returns:
Report with
status,code,message,complete,seconds,work,vertices,triangles,quads,bytes(bytes written) andlosses(attribute categories dropped by an allowed lossy 2DM write).- Return type:
- Raises:
TypeError –
meshis not aMeshResult.ValueError – The extension is not
.mkbor.2dm, or an option is invalid.