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

points

float64 buffer (N, 2) or rows [x, y]

Required. Source points in one Cartesian XY frame, at most 20 million. Paths index them from zero. Exact XY duplicates share one vertex.

paths

list of dict

Constraint paths over points; see Paths. An outer path is required.

options

dict

Sizing, cell and quality options; see Options.

metadata

dict

Units and description; see Metadata.

point_elevations

sequence of float, one per point

Authored heights. NaN takes the height from the terrain raster (or flat_elevation without one). Coincident points must agree.

point_ids

sequence of int64, one per point

External IDs of the vertices made from these points (vertex_ids); default: one-based point order. Generated vertices get IDs above the highest. A point that shares a vertex with an earlier one keeps its ID as an alias (alias_ids).

point_markers

sequence of int32, one per point

Markers of those vertices (vertex_markers), kept the same way.

quad_regions

list of dict

Areas to fill with quadrilaterals; see Quadrilateral regions.

size_field

dict

Sizes that grade away from the constraints; see Size field.

region_seeds

list of {"point": [x, y], "region": int}

Assign a region number to the constrained area containing each point. A seed must lie strictly inside the domain; conflicting seeds fail.

labels

list of {"id": int, "name": str}

Names for region numbers, carried into the result and .mkb files.

Paths#

Key

Default

Meaning

vertices

—

Required. Indexes into points.

kind

"line"

"outer" bounds the domain (outer paths form a union), "hole" is subtracted from it, "region" and "line" force mesh edges along themselves.

closed

False

Outer, hole and region paths close implicitly; a line closes only when this is true.

marker

0

Integer carried with the path.

id

0

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

horizontal_metres_per_unit

1

Metres per XY unit. Must be positive.

vertical_metres_per_unit

1

Metres per Z unit. Must be positive.

units_known

True

False refuses the job (code units_required).

crs

""

Coordinate reference system text, stored, never used to transform.

description

""

Free text, stored with the mesh.

Sizes and distances are in XY units; heights and terrain tolerances in Z units.

Options#

Key

Default

Meaning

cells

"triangles"

"triangles", or "mixed" to plan mapped quadrilateral patches with triangle infill.

maximum_size

0

Largest nominal cell size; 0 sets no global limit.

minimum_target

0

Advisory smallest target size; constraints may still need smaller cells. 0 uses a quarter of maximum_size. Must not exceed maximum_size.

minimum_edge

0

Shortest edge allowed in the result; 0 does not check.

minimum_angle_degrees

30

Smallest triangle angle refinement aims for; at most 34.

adjacent_ratio

0

Largest size ratio between neighbouring cells; 0 does not check, otherwise at least 1.

flat_elevation

0

Height used where neither an authored height nor a raster applies.

smoothing_passes

0

Vertex smoothing passes, 0–10.

coarsen_passes

0

Passes that remove generated vertices where sizing allows (and, with a raster, where the terrain bound is certified), 0–10.

coarsening_order

"legacy_flatness"

Order of coarsening candidates: "legacy_flatness" or "resolution_aware".

coarsening_reference_size

10

Reference size for the resolution_aware order. Must be positive.

sizing_repair_passes

2

Passes that refine cells breaking a size requirement, 0–3.

repair_insertions

200000

Most vertices the repair passes may insert.

terrain_tolerance

0

Largest allowed gap between the mesh surface and the raster, in Z units; 0 disables terrain checks. Needs a raster; see Terrain.

terrain_policy

constant

How the tolerance varies with cell size; see Terrain.

strict_sizing

True

Refuse the job when maximum-size, edge or transition requirements remain unmet, instead of returning it with exceptions.

require_terrain_certification

False

Refuse the job when any cell’s terrain bound is unknown or unmet.

retain_input_mapping

True

Fill input_mapping.

automatic_blocks

False

With "mixed", also place quadrilateral blocks in open areas.

maximum_patch_cells

250000

Cell limit per planned quadrilateral patch.

maximum_automatic_blocks

4096

Limit on automatic blocks.

limits

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

max_vertices

20,000,000

Vertices in the result.

max_cells

20,000,000

Cells in the result.

max_edges

40,000,000

Edges in the result.

max_workspace_bytes

4 GiB

Estimated working memory.

max_work

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).

max_metadata_bytes

8 MiB

Metadata size (file I/O).

max_record_bytes

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

heights

—

Required. Node samples, row index increasing in +Y, at least 2 × 2 and at most 100 million. NaN marks missing data.

origin

[0, 0]

XY of the first sample.

spacing

[1, 1]

Sample spacing in X and Y.

maximum_cells_per_query

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

mode

"constant"

"constant" uses terrain_tolerance everywhere. "target_size" scales it by size / reference_size, clamped to the range below.

reference_size

10

Size at which the tolerance equals terrain_tolerance.

minimum_tolerance

0

Lower clamp.

maximum_tolerance

0

Upper clamp; 0 uses terrain_tolerance.

Quadrilateral regions#

Each entry in quad_regions describes an area to fill with mapped quadrilaterals when cells is "mixed".

Key

Default

Meaning

ring

—

Required. Outline as rows [x, y] or a float64 (N, 2) buffer; simple, either orientation, closing point optional.

cells

"auto"

"required_quads" fails the job if the region cannot be mapped; "auto" falls back to triangles; "triangles" keeps the outline as a constraint but meshes the inside with triangles.

spacing

0

Quadrilateral edge length; 0 derives it from the sizing.

h_along, h_across

0

Separate spacings along and across along_angle_degrees; setting either makes the spacing directional, with no isotropic fallback.

along_angle_degrees

0

Direction of the along axis, degrees counter-clockwise from +x.

aspect_max

-1

Limit on the ratio of opposite side means; negative inherits the global limit, 0 is unbounded.

corners

automatic

Four ring vertex indexes, in ring order, to use as the patch corners.

holes

none

Rings subtracted from the region.

attribute

0

Integer stored with the region.

tag

""

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

near_size

0

Edge length at the constraints. Must be positive.

gradation

0.25

Growth of size per unit distance; typically 0.1–0.5.

max_size

0

Upper clamp on the size; 0 is unbounded.

area_floor

0

Smallest cell area the field asks for; 0 sets no floor.

max_grid_cells

4,000,000

Background grid budget.

regions

none

{"ring": ..., "size": h} rows; inside a ring the size is at most h.

terrain_regions

none

Rows of the same form, used only by terrain footprint queries.