Loading...
Searching...
No Matches
job.hpp
Go to the documentation of this file.
1// SPDX-License-Identifier: Apache-2.0
2#pragma once
3#include "mesh.hpp"
4#include "terrainpolicy.hpp"
5#include "planning.hpp"
6#include "sizefield.hpp"
7#include <optional>
8#include <functional>
9
10namespace meshkit
11{
13enum class CellPlan : std::uint8_t { Triangles, AutomaticMixed };
20
28struct RegionSeed {
34 std::int32_t region = 0;
35};
36
141
154 std::vector<Point2> points;
159 std::vector<Path> paths;
162 std::vector<double> pointElevations;
167 std::vector<std::int64_t> pointIds;
172 std::vector<std::int32_t> pointMarkers;
174 std::vector<Label> labels;
175 std::vector<RegionSeed> regions;
181 std::vector<plan::QuadRegion> quadRegions;
186 std::vector<plan::PatchMesh> fixedPatches;
191 std::optional<plan::SizeFieldOptions> sizeField;
194};
195
204struct Providers {
205 // Immutable, synchronous native callbacks on the job thread. They must not
206 // reenter the job or mutate request arrays. Exceptions end the job without a mesh:
207 // std::bad_alloc as ResourceLimit, other exceptions as Failed.
208 // Footprint bounds include every prescribed source, including narrow strips.
213 std::function<double(const Box2 &)> maximumSize;
219 std::function<double(double, double)> elevation;
225 std::function<double(const Point2 *, const double *, Point2 *)> terrainWitness;
231 std::function<double(const Point2 *, const double *)> terrainBound;
233 std::function<bool()> cancelled;
234 std::string identity;
235};
236
239 std::string code;
253 double measured = 0, allowed = 0;
254};
255
263 std::string algorithmVersion = "cdt-1/job-2";
269 std::string providerIdentity;
272 std::uint64_t constraintSegments = 0;
281 std::uint64_t plannedPatches = 0, sharedSides = 0, planningRetries = 0;
286 std::vector<plan::PatchDecision> planning;
297 std::uint64_t inserted = 0, removed = 0, removalAttempts = 0, queuePeak = 0;
316 std::uint64_t terrainConflicts = 0, terrainUnknown = 0;
326 std::vector<JobException> examples; // At most 64, never one object per cell.
327};
328
338
352 bool qtFree = true, triangles = true, automaticMixed = true;
361 bool terrainProviders = true, coarsening = true, streamingIO = true;
362};
363
368{
369 return {};
370}
371// Borrowed immutable inputs for this synchronous call; owned result buffers.
372// No mesh is returned on infeasible/cancelled/resource/failed jobs. The native
373// backend supports triangles and jointly planned mapped/automatic mixed meshes.
374// CompleteWithExceptions is distinct from a certified result. No CRS conversion,
375// DEM access, Python callbacks, or file publication occurs inside runJob.
398JobResult runJob(const JobRequest &, const Providers & = {}, EventChannel *events = nullptr);
399}
Axis-aligned rectangle in the XY plane, stored as an origin corner and a signed size.
Definition geometry.hpp:167
Bounded, thread-safe event queue between one job and its consumer.
Definition events.hpp:169
Point or displacement vector in the horizontal (XY) plane.
Definition geometry.hpp:21
The Qt-facing MeshKit API (meshkit::core_qt, meshkit::model_qt, meshkit::io_qt): mesh value types and...
The Qt-free MeshKit library: job events and progress (meshkit::runtime), the neutral mesh model,...
JobResult runJob(const JobRequest &, const Providers &={}, EventChannel *events=nullptr)
Run one meshing job synchronously on the calling thread.
Definition job.cpp:1151
std::uint32_t Index
Zero-based index into a native vertex, cell or edge array.
Definition mesh.hpp:13
constexpr Capabilities nativeCapabilities()
Feature flags of this native build.
Definition job.hpp:367
CoarseningOrder
Order in which terrain coarsening tries to remove free vertices.
Definition terrainpolicy.hpp:10
@ LegacyFlatness
Flattest vertex star first (smallest facet-normal spread), tile by tile in spatial (Morton) order.
Definition terrainpolicy.hpp:10
constexpr Index missingIndex
Sentinel index (all bits set, 4294967295) meaning "no index".
Definition mesh.hpp:20
CellPlan
Cell types a job may deliver (JobOptions::cells).
Definition job.hpp:13
@ Triangles
Triangles only.
Definition job.hpp:13
@ AutomaticMixed
Jointly planned mapped quad patches (plus optional automatic blocks) with triangle infill.
Definition job.hpp:13
Graded element sizing for Delaunay refinement (MESH_MINSIZE_ENFORCEMENT_V2_AND_GRADING_PLAN_2026-09-0...
Feature flags of the native backend, as returned by nativeCapabilities().
Definition job.hpp:343
bool streamingIO
Streaming mesh file I/O is supported.
Definition job.hpp:361
bool coarsening
Coarsening (JobOptions::coarsenPasses) is supported.
Definition job.hpp:361
bool triangles
Triangle-only jobs (CellPlan::Triangles) are supported.
Definition job.hpp:352
bool qtFree
The native core and I/O need no Qt.
Definition job.hpp:352
bool terrainProviders
Terrain provider callbacks (see Providers) are supported.
Definition job.hpp:361
bool automaticMixed
Mixed triangle/quad jobs (CellPlan::AutomaticMixed) are supported.
Definition job.hpp:352
One requirement exception recorded by runJob() as a bounded example.
Definition job.hpp:237
double measured
Measured value: nominal size or edge length (XY units), size ratio, or terrain bound (Z units); 0 for...
Definition job.hpp:253
std::string code
Kind of exception: "size", "edge", "transition", "terrain" or "terrain_unknown".
Definition job.hpp:239
Index cell
Index of the cell in the job's output Mesh::cells (for "transition", the lower of the two cell indice...
Definition job.hpp:244
double allowed
Limit it was compared with: the size bound, JobOptions::minimumEdge, JobOptions::adjacentRatio,...
Definition job.hpp:253
Meshing policy of a JobRequest.
Definition job.hpp:44
double maximumSize
Global upper bound on nominal cell size, finite and >= 0; 0 (default) means no global bound.
Definition job.hpp:65
std::uint32_t repairInsertions
Cap on vertices inserted by sizing repair; default 200 000.
Definition job.hpp:93
bool requireTerrainCertification
When true, any terrain conflict or unknown terrain bound fails the job (code "unverified_terrain",...
Definition job.hpp:125
double terrainTolerance
Reference terrain tolerance in Z units, finite and >= 0; 0 (default) disables terrain checks.
Definition job.hpp:106
std::uint64_t maximumPatchCells
Most cells one mapped patch may hold; default 250 000.
Definition job.hpp:131
int coarsenPasses
Maximum coarsening (removal) attempts per free vertex, i.e.
Definition job.hpp:87
int sizingRepairPasses
Bounded sizing-repair passes after smoothing, terrain insertion and coarsening, 0 to 3; default 2.
Definition job.hpp:87
double minimumTarget
Advisory minimum nominal cell size, finite and >= 0; 0 (default) disables it.
Definition job.hpp:65
bool automaticBlocks
Whether patch planning also places automatic open-area quad blocks; default false.
Definition job.hpp:137
int smoothingPasses
Passes of non-degrading smoothing of free vertices after size and angle refinement,...
Definition job.hpp:87
bool retainInputMapping
When true (default), JobResult::inputVertexToOutput is filled.
Definition job.hpp:125
double minimumEdge
Minimum actual edge length, finite and >= 0; 0 (default) disables it.
Definition job.hpp:65
double flatElevation
Elevation (Z units, finite; default 0) given to vertices without a finite authored height when Provid...
Definition job.hpp:75
bool strictSizing
When true (default), remaining size, edge or transition conflicts fail the job (code "unresolved_size...
Definition job.hpp:125
TerrainTolerancePolicy terrainPolicy
Footprint tolerance policy; must be TerrainTolerancePolicy::valid(), and its TargetSize mode needs a ...
Definition job.hpp:111
Limits limits
Resource caps of the job.
Definition job.hpp:139
int maximumAutomaticBlocks
Cap on automatic block tiles; default 4096.
Definition job.hpp:138
double adjacentRatio
Largest allowed ratio between the nominal sizes of two cells sharing a side: 0 (default) disables it,...
Definition job.hpp:75
CellPlan cells
Cell types to deliver; default triangles only.
Definition job.hpp:45
double coarseningReferenceSize
Positive finite size (XY units; default 10) that resolution-aware coarsening uses as the target where...
Definition job.hpp:106
CoarseningOrder coarseningOrder
Order in which coarsening tries vertices; default CoarseningOrder::LegacyFlatness.
Definition job.hpp:95
double minimumAngleDegrees
Smallest triangle angle sought by refinement, in degrees from 0 to 34; default.
Definition job.hpp:65
Report of runJob(): the OperationReport fields plus options, provider identity, planning,...
Definition job.hpp:262
std::uint64_t removalAttempts
Coarsening removal attempts.
Definition job.hpp:297
double largestTerrainRatio
Largest terrain bound / tolerance over cells with a known bound; 0 when terrain is not checked.
Definition job.hpp:324
std::string algorithmVersion
Algorithm and report version identifier.
Definition job.hpp:263
JobOptions resolvedOptions
Copy of the options of the returned attempt as supplied (zero defaults such as Limits::maxWork are no...
Definition job.hpp:268
std::uint64_t transitionConflicts
Shared sides whose cell size ratio exceeds JobOptions::adjacentRatio.
Definition job.hpp:309
std::uint64_t belowMinimum
Cells whose nominal size is below JobOptions::minimumTarget (advisory).
Definition job.hpp:309
std::uint64_t edgeConflicts
Cell sides shorter than JobOptions::minimumEdge, counted per cell (a shared side counts twice).
Definition job.hpp:309
std::uint64_t constraintSegments
Source segments checked by that audit.
Definition job.hpp:272
bool constraintAuditPassed
Whether the independent audit of the delivered source constraints passed.
Definition job.hpp:271
std::uint64_t queuePeak
Peak size of the coarsening priority queue.
Definition job.hpp:297
std::uint64_t terrainUnknown
Cells whose terrain bound is unknown (nonfinite or negative).
Definition job.hpp:316
double largestAdjacentRatio
Largest nominal-size ratio over all shared sides; 1 when none was measured.
Definition job.hpp:324
std::uint64_t sizeConflicts
Cells whose nominal size exceeds the size bound over their bounding box.
Definition job.hpp:309
std::vector< JobException > examples
Up to 64 individual exceptions; the counters above hold the totals.
Definition job.hpp:326
std::uint64_t terrainConflicts
Cells whose certified terrain bound exceeds their footprint tolerance.
Definition job.hpp:316
std::uint64_t sharedSides
Patch sides shared between planned patches.
Definition job.hpp:281
std::string providerIdentity
Copy of Providers::identity.
Definition job.hpp:269
std::uint64_t plannedPatches
Quad patches (fixed and planned) prepared for the returned attempt.
Definition job.hpp:281
std::vector< plan::PatchDecision > planning
Patch planning decisions of the returned attempt followed by those of earlier retries; at most 256.
Definition job.hpp:286
std::uint64_t removed
Vertices removed by coarsening.
Definition job.hpp:297
std::uint64_t planningRetries
Mixed-interface retries before the returned attempt, 0 to 3.
Definition job.hpp:281
std::uint64_t inserted
Vertices inserted by refinement, segment splits included.
Definition job.hpp:297
Complete input of runJob(): source geometry, optional attributes, sizing inputs, metadata and options...
Definition job.hpp:148
std::vector< Label > labels
Region names copied to Mesh::labels; ids must be unique and names UTF-8.
Definition job.hpp:174
std::optional< plan::SizeFieldOptions > sizeField
Optional graded size field built from the source paths and marked points; its bound is combined with ...
Definition job.hpp:191
Metadata metadata
Units, CRS text and description; copied to the delivered mesh.
Definition job.hpp:192
std::vector< double > pointElevations
Optional authored Z per point; NaN samples the elevation provider, or uses JobOptions::flatElevation ...
Definition job.hpp:162
std::vector< std::int64_t > pointIds
Positive, unique external ids of points; empty means 1, 2, 3, ... Generated vertices get ids above th...
Definition job.hpp:167
std::vector< Point2 > points
Mandatory source points: at least three, at most Limits::maxVertices.
Definition job.hpp:154
std::vector< plan::PatchMesh > fixedPatches
Local quad patches inserted as given after validation; every cell centre must lie in the domain.
Definition job.hpp:186
JobOptions options
Meshing policy and limits.
Definition job.hpp:193
std::vector< Path > paths
Source paths indexing points; at least one PathKind::Outer path is required (no bounding box is infer...
Definition job.hpp:159
std::vector< plan::QuadRegion > quadRegions
Quad region policies (see plan::QuadRegion).
Definition job.hpp:181
std::vector< RegionSeed > regions
Seeds that assign region ids to constrained components.
Definition job.hpp:175
std::vector< std::int32_t > pointMarkers
Markers of points, delivered as vertex markers; empty means all zero.
Definition job.hpp:172
Owned output of runJob().
Definition job.hpp:329
JobReport report
Status, counters and diagnostics of the job.
Definition job.hpp:336
std::vector< Index > inputVertexToOutput
Output vertex index of each JobRequest::points entry when JobOptions::retainInputMapping is set; empt...
Definition job.hpp:335
Resource caps for jobs, validation and file I/O.
Definition mesh.hpp:198
Neutral owned mesh: XYZ vertices, triangle/quad cells, marked edges, paths, optional external ids and...
Definition mesh.hpp:159
Physical units, coordinate reference text and description of a mesh or job request.
Definition mesh.hpp:125
Versioned outcome of a native operation: mesh validation, file I/O, or a job (as the base of JobRepor...
Definition mesh.hpp:232
Optional caller callbacks used by runJob(), plus the provider identity.
Definition job.hpp:204
std::function< double(const Point2 *, const double *)> terrainBound
Certified maximum residual (Z units) of the linear triangle over three XY corners with the given heig...
Definition job.hpp:231
std::function< double(const Point2 *, const double *, Point2 *)> terrainWitness
Refinement witness: given three XY corners and their heights, returns the triangle's residual against...
Definition job.hpp:225
std::function< bool()> cancelled
Polled during the job; returning true stops it with RunStatus::Cancelled.
Definition job.hpp:233
std::string identity
Caller supplied dataset/provider version or fingerprint.
Definition job.hpp:234
std::function< double(double, double)> elevation
Elevation (Z units) at XY position (x, y).
Definition job.hpp:219
std::function< double(const Box2 &)> maximumSize
Upper bound on nominal cell size (XY units) over a whole footprint box.
Definition job.hpp:213
Point that assigns a region id to the constrained component containing it.
Definition job.hpp:28
Point2 point
Seed position in XY plane units; must be finite, inside the delivered domain and not on a delivered c...
Definition job.hpp:33
std::int32_t region
Region id given to every cell of the component.
Definition job.hpp:34
Maps a reference terrain tolerance and a footprint target size to the tolerance used there.
Definition terrainpolicy.hpp:36