Requests and options#
A meshing job is described by one dict, passed to meshkit.run()
or meshkit.start(). Every mapping in it must be a dict; an unknown
key or a value of the wrong type raises ValueError before the job
starts. Values that are well-typed but inconsistent (an option out of range,
mismatched array lengths, missing units) do not raise: the job finishes with
status infeasible and a code such as option, size_range or
units_required in its report.
The request#
Key |
Type |
Meaning |
|---|---|---|
|
float64 buffer |
Required. Source points in one Cartesian XY frame, at most 20 million. Paths index them from zero. Exact XY duplicates share one vertex. |
|
list of |
Constraint paths over |
|
Sizing, cell and quality options; see Options. |
|
|
Units and description; see Metadata. |
|
|
sequence of float, one per point |
Authored heights. NaN takes the height from the terrain raster (or
|
|
sequence of int64, one per point |
External IDs of the vertices made from these points
( |
|
sequence of int32, one per point |
Markers of those vertices ( |
|
list of |
Areas to fill with quadrilaterals; see Quadrilateral regions. |
|
Sizes that grade away from the constraints; see Size field. |
|
|
list of |
Assign a region number to the constrained area containing each point. A seed must lie strictly inside the domain; conflicting seeds fail. |
|
list of |
Names for region numbers, carried into the result and |
Paths#
Key |
Default |
Meaning |
|---|---|---|
|
— |
Required. Indexes into |
|
|
|
|
|
Outer, hole and region paths close implicitly; a line closes only when this is true. |
|
|
Integer carried with the path. |
|
|
Integer identifier carried with the path. |
Crossing paths must be split at their intersections before meshing:
meshkit.prepare_sources() does not node crossings, and the job rejects
them. Exactly shared vertices and overlapping stretches need no welding.
Metadata#
Key |
Default |
Meaning |
|---|---|---|
|
|
Metres per XY unit. Must be positive. |
|
|
Metres per Z unit. Must be positive. |
|
|
False refuses the job (code |
|
|
Coordinate reference system text, stored, never used to transform. |
|
|
Free text, stored with the mesh. |
Sizes and distances are in XY units; heights and terrain tolerances in Z units.
Options#
Key |
Default |
Meaning |
|---|---|---|
|
|
|
|
|
Largest nominal cell size; 0 sets no global limit. |
|
|
Advisory smallest target size; constraints may still need smaller cells.
0 uses a quarter of |
|
|
Shortest edge allowed in the result; 0 does not check. |
|
|
Smallest triangle angle refinement aims for; at most 34. |
|
|
Largest size ratio between neighbouring cells; 0 does not check, otherwise at least 1. |
|
|
Height used where neither an authored height nor a raster applies. |
|
|
Vertex smoothing passes, 0–10. |
|
|
Passes that remove generated vertices where sizing allows (and, with a raster, where the terrain bound is certified), 0–10. |
|
|
Order of coarsening candidates: |
|
|
Reference size for the |
|
|
Passes that refine cells breaking a size requirement, 0–3. |
|
|
Most vertices the repair passes may insert. |
|
|
Largest allowed gap between the mesh surface and the raster, in Z units; 0 disables terrain checks. Needs a raster; see Terrain. |
|
constant |
How the tolerance varies with cell size; see Terrain. |
|
|
Refuse the job when maximum-size, edge or transition requirements remain unmet, instead of returning it with exceptions. |
|
|
Refuse the job when any cell’s terrain bound is unknown or unmet. |
|
|
Fill |
|
|
With |
|
|
Cell limit per planned quadrilateral patch. |
|
|
Limit on automatic blocks. |
|
see below |
Resource limits. |
Nominal size is the side of the equilateral triangle of equal area for a triangle, and the square root of the area for a quadrilateral.
Limits#
limits bounds counts, estimated workspace and orchestration work; it does
not bound process memory or time spent elsewhere. A job that reaches a limit
returns status resource_limit with no geometry.
Key |
Default |
Meaning |
|---|---|---|
|
20,000,000 |
Vertices in the result. |
|
20,000,000 |
Cells in the result. |
|
40,000,000 |
Edges in the result. |
|
4 GiB |
Estimated working memory. |
|
0 |
Work units for the job’s own counter (0 = 20 billion), also passed as the budget of patch planning and the final constraint audit (0 = sized from their inputs). |
|
8 MiB |
Metadata size (file I/O). |
|
1 MiB |
Size of one file record (file I/O). |
Terrain#
Pass a raster to meshkit.run() or meshkit.start() to give the job
heights and a terrain error check:
raster = {"heights": dem, # float32 or float64, shape (rows, columns)
"origin": [x0, y0], # coordinates of heights[0, 0]
"spacing": [dx, dy]} # positive
result = meshkit.run(request, raster=raster, provider_identity="dem-2026-v1")
Key |
Default |
Meaning |
|---|---|---|
|
— |
Required. Node samples, row index increasing in +Y, at least 2 × 2 and at most 100 million. NaN marks missing data. |
|
|
XY of the first sample. |
|
|
Sample spacing in X and Y. |
|
4,000,000 |
Raster cells one bound query may visit. |
The raster is a bilinear surface. For each triangular facet MeshKit checks its
whole intersection with the raster cells, including extremes along clipped
edges, and reports the largest gap. Missing data is unknown, not interpolated
across. The check concerns this surface, not the accuracy of the source DEM.
provider_identity is copied into the report as evidence of which dataset
was used; MeshKit does not compute or check it.
terrain_policy makes the tolerance grow with cell size:
Key |
Default |
Meaning |
|---|---|---|
|
|
|
|
|
Size at which the tolerance equals |
|
|
Lower clamp. |
|
|
Upper clamp; 0 uses |
Quadrilateral regions#
Each entry in quad_regions describes an area to fill with mapped
quadrilaterals when cells is "mixed".
Key |
Default |
Meaning |
|---|---|---|
|
— |
Required. Outline as rows |
|
|
|
|
|
Quadrilateral edge length; 0 derives it from the sizing. |
|
|
Separate spacings along and across |
|
|
Direction of the along axis, degrees counter-clockwise from +x. |
|
|
Limit on the ratio of opposite side means; negative inherits the global limit, 0 is unbounded. |
|
automatic |
Four ring vertex indexes, in ring order, to use as the patch corners. |
|
none |
Rings subtracted from the region. |
|
|
Integer stored with the region. |
|
|
Text tag for the region’s cells; empty inherits the region marker’s. |
Size field#
size_field grades sizes from near_size at the constraints outward at
the rate gradation, with polygon overrides.
Key |
Default |
Meaning |
|---|---|---|
|
|
Edge length at the constraints. Must be positive. |
|
|
Growth of size per unit distance; typically 0.1–0.5. |
|
|
Upper clamp on the size; 0 is unbounded. |
|
|
Smallest cell area the field asks for; 0 sets no floor. |
|
4,000,000 |
Background grid budget. |
|
none |
|
|
none |
Rows of the same form, used only by terrain footprint queries. |