Loading...
Searching...
No Matches
meshkit Namespace Reference

The Qt-free MeshKit library: job events and progress (meshkit::runtime), the neutral mesh model, meshing jobs, the constrained Delaunay kernel and terrain surfaces (meshkit::core), and the MKB and SMS 2DM codecs (meshkit::io). More...

Namespaces

namespace  cdt_detail
 Internals of the constrained Delaunay kernel implementation; not part of the supported API.
 
namespace  detail
 Storage policies and containers for the constrained Delaunay kernel and the plan model: StandardStorage (standard containers) and QtStorage (Qt containers).
 
namespace  native_detail
 Implementation helpers of the native jobs and codecs (failure signalling, work accounting, file publication); not installed and not part of the supported API.
 
namespace  plan
 Planning algorithms on standard containers: quad patch planning and placement, size fields, source-geometry simplification and the independent constraint and sizing audits.
 

Classes

class  BasicConstrainedDelaunay
 Constrained Delaunay triangulation kernel with quality and terrain refinement and optional coarsening (see the file comment for the algorithms). More...
 
class  Box2
 Axis-aligned rectangle in the XY plane, stored as an origin corner and a signed size. More...
 
struct  Capabilities
 Feature flags of the native backend, as returned by nativeCapabilities(). More...
 
struct  Cell
 Triangle or quadrilateral cell of a Mesh. More...
 
class  CoarseningQueue
 Indexed binary min-heap holding at most one entry per vertex for resolution-aware coarsening. More...
 
struct  Counts
 Vertex and cell counters of an operation or event; -1 marks a value not available. More...
 
struct  Edge
 Marked edge between two vertices of a Mesh. More...
 
struct  Event
 One job notification passed through an EventChannel. More...
 
class  EventChannel
 Bounded, thread-safe event queue between one job and its consumer. More...
 
struct  GenerationProgress
 Counter snapshot passed to ConstrainedDelaunay::QualityOptions::onProgress during refineQuality(). More...
 
struct  IOOptions
 Options shared by the MKB and 2DM readers and writers. More...
 
struct  IOReport
 Outcome of one read or write: status, code, message, counts, timing and byte total. More...
 
struct  JobException
 One requirement exception recorded by runJob() as a bounded example. More...
 
struct  JobOptions
 Meshing policy of a JobRequest. More...
 
struct  JobReport
 Report of runJob(): the OperationReport fields plus options, provider identity, planning, refinement and certification statistics. More...
 
struct  JobRequest
 Complete input of runJob(): source geometry, optional attributes, sizing inputs, metadata and options. More...
 
struct  JobResult
 Owned output of runJob(). More...
 
struct  Label
 Name of a region identifier used by Cell::region. More...
 
struct  Limits
 Resource caps for jobs, validation and file I/O. More...
 
struct  Mesh
 Neutral owned mesh: XYZ vertices, triangle/quad cells, marked edges, paths, optional external ids and markers, region labels, source aliases and metadata. More...
 
struct  Metadata
 Physical units, coordinate reference text and description of a mesh or job request. More...
 
struct  OperationReport
 Versioned outcome of a native operation: mesh validation, file I/O, or a job (as the base of JobReport). More...
 
struct  Path
 Indexed polyline or ring: a source constraint of a JobRequest, or a delivered path of a Mesh. More...
 
class  Point2
 Point or displacement vector in the horizontal (XY) plane. More...
 
struct  Point3
 Plain x, y, z coordinate triple; the vertex type of meshkit::Mesh. More...
 
struct  Providers
 Optional caller callbacks used by runJob(), plus the provider identity. More...
 
struct  RasterData
 Regular grid of elevation samples at nodes, in the mesh's XY and Z units. More...
 
struct  RasterQuery
 Result of RasterSurface::query() for one triangle. More...
 
class  RasterSurface
 Immutable bilinear elevation surface over a RasterData grid. More...
 
struct  ReadResult
 Mesh and report returned by the readers. More...
 
struct  RegionSeed
 Point that assigns a region id to the constrained component containing it. More...
 
struct  TerrainTolerancePolicy
 Maps a reference terrain tolerance and a footprint target size to the tolerance used there. More...
 
struct  VertexAlias
 Extra source identity merged into a shared output vertex. More...
 

Typedefs

using ConstrainedDelaunay = BasicConstrainedDelaunay<detail::StandardStorage>
 Kernel instantiated with standard C++ storage (Point2, Box2, std::string, std::vector-based containers).
 
using Index = std::uint32_t
 Zero-based index into a native vertex, cell or edge array.
 

Enumerations

enum class  Severity {
  Info ,
  Warning ,
  Error
}
 Severity of an Event. More...
 
enum class  EventKind {
  Stage ,
  Progress ,
  Diagnostic ,
  StageCompleted ,
  Completed
}
 Kind of an Event. More...
 
enum class  RunStatus {
  Running ,
  Complete ,
  CompleteWithExceptions ,
  ResourceLimit ,
  Cancelled ,
  Failed ,
  Infeasible
}
 Status of a running or finished operation (see statusName()). More...
 
enum class  UnknownRecords {
  Reject ,
  IgnoreWithReport
}
 How read2dm() treats a card other than MESH2D, ND, E3T, E4Q or NS. More...
 
enum class  CellPlan : std::uint8_t {
  Triangles ,
  AutomaticMixed
}
 Cell types a job may deliver (JobOptions::cells). More...
 
enum class  PathKind : std::uint8_t {
  Outer ,
  Hole ,
  Line ,
  Region
}
 Role of a Path in a JobRequest or a delivered Mesh. More...
 
enum class  CoarseningOrder {
  LegacyFlatness ,
  ResolutionAware
}
 Order in which terrain coarsening tries to remove free vertices. More...
 
enum class  TerrainToleranceMode {
  Constant ,
  TargetSize
}
 How TerrainTolerancePolicy::tolerance() derives a footprint's terrain tolerance. More...
 

Functions

const char * statusName (RunStatus status) noexcept
 Stable lower-case name of a status, as used by the Python bindings.
 
ReadResult readBinary (std::istream &, const IOOptions &={})
 Read a version-1 MeshKit binary (MKB) mesh from a stream.
 
ReadResult readBinary (const std::filesystem::path &, const IOOptions &={})
 Open a file in binary mode and read it as MKB, as the stream overload does.
 
IOReport writeBinary (const std::filesystem::path &, const Mesh &, const IOOptions &={})
 Validate a mesh and atomically publish it to a path as version-1 MKB.
 
ReadResult read2dm (const std::filesystem::path &, const IOOptions &={})
 Read an SMS 2DM file in two passes (nodes, then elements and node strings).
 
IOReport write2dm (const std::filesystem::path &, const Mesh &, const IOOptions &={})
 Validate a mesh and atomically publish it to a path as SMS 2DM.
 
constexpr Capabilities nativeCapabilities ()
 Feature flags of this native build.
 
JobResult runJob (const JobRequest &, const Providers &={}, EventChannel *events=nullptr)
 Run one meshing job synchronously on the calling thread.
 
OperationReport validateMesh (const Mesh &, const Limits &={}, const std::function< bool()> &cancelled={})
 Check a mesh's local validity without modifying it.
 
double resolutionRemovalImportance (double flatness, double actualSize, double targetSize)
 Rank a vertex for resolution-aware coarsening; lower values are tried first.
 

Variables

constexpr Index missingIndex = ~Index(0)
 Sentinel index (all bits set, 4294967295) meaning "no index".
 

Detailed Description

The Qt-free MeshKit library: job events and progress (meshkit::runtime), the neutral mesh model, meshing jobs, the constrained Delaunay kernel and terrain surfaces (meshkit::core), and the MKB and SMS 2DM codecs (meshkit::io).

Standard C++17 only; see NATIVE_API.md for units, ownership and error reporting.

Typedef Documentation

◆ ConstrainedDelaunay

Kernel instantiated with standard C++ storage (Point2, Box2, std::string, std::vector-based containers).

◆ Index

using meshkit::Index = std::uint32_t

Zero-based index into a native vertex, cell or edge array.

Enumeration Type Documentation

◆ CellPlan

enum class meshkit::CellPlan : std::uint8_t
strong

Cell types a job may deliver (JobOptions::cells).

Enumerator
Triangles 

Triangles only.

Quad regions still add their outlines and spacing caps but get no quads; fixed patches are rejected (code "quad_conflict").

AutomaticMixed 

Jointly planned mapped quad patches (plus optional automatic blocks) with triangle infill.

◆ CoarseningOrder

enum class meshkit::CoarseningOrder
strong

Order in which terrain coarsening tries to remove free vertices.

Enumerator
LegacyFlatness 

Flattest vertex star first (smallest facet-normal spread), tile by tile in spatial (Morton) order.

ResolutionAware 

Lowest resolutionRemovalImportance() first, then lowest actual/target size ratio, tile by tile; the refinement options must then supply a target-size callback, a positive reference size and a positive vertical-to-XY normal scale.

◆ EventKind

enum class meshkit::EventKind
strong

Kind of an Event.

Enumerator
Stage 

A stage has started; Event::stage names it.

Progress 

Progress within a stage.

EventChannel::publish() overwrites the newest pending event instead of queueing another when that is a Progress event of the same stage.

Diagnostic 

Informational diagnostic, e.g.

a patch planning retry; the Event default.

StageCompleted 

A stage has finished.

Completed 

Final event of a job, carrying its final status; the channel ignores later events.

◆ PathKind

enum class meshkit::PathKind : std::uint8_t
strong

Role of a Path in a JobRequest or a delivered Mesh.

runJob() closes Outer, Hole and Region rings implicitly; a Line stays open unless Path::closed is set. runJob() and validateMesh() reject values above Region.

Enumerator
Outer 

Outer domain ring; the domain is the union of all outer rings minus the holes.

Hole 

Ring subtracted from the domain; cells inside it are removed.

Line 

Constrained polyline (breakline) whose segments become chains of cell edges.

Region 

Closed constrained ring inside the domain; it separates region-label components but does not add or remove domain area.

◆ RunStatus

enum class meshkit::RunStatus
strong

Status of a running or finished operation (see statusName()).

Enumerator
Running 

Still running; carried by intermediate events.

Complete 

Finished; every checked requirement holds.

CompleteWithExceptions 

Finished with a result, but with recorded exceptions.

ResourceLimit 

Stopped at a resource cap or allocation failure; no result.

Cancelled 

Stopped because cancellation was requested; no result.

Failed 

Stopped by an error such as an exception or I/O error; no result.

Infeasible 

Input or policy cannot be satisfied; no result.

◆ Severity

enum class meshkit::Severity
strong

Severity of an Event.

Enumerator
Info 

Informational; the default.

Warning 

Warning-level notification.

Error 

Failure; runJob() uses it for a Completed event of a job that did not complete.

◆ TerrainToleranceMode

enum class meshkit::TerrainToleranceMode
strong

How TerrainTolerancePolicy::tolerance() derives a footprint's terrain tolerance.

Enumerator
Constant 

Use the reference tolerance everywhere.

TargetSize 

Scale the reference tolerance linearly with the footprint's target size h.

◆ UnknownRecords

enum class meshkit::UnknownRecords
strong

How read2dm() treats a card other than MESH2D, ND, E3T, E4Q or NS.

Blank lines and lines whose first token starts with # or ;; are always skipped. The MKB functions ignore this setting.

Enumerator
Reject 

Fail the read with code unsupported_card (the default).

IgnoreWithReport 

Skip the card, count it in IOReport::ignoredRecords, record a bounded ignored_card:<card> code in IOReport::losses and finish CompleteWithExceptions.

Function Documentation

◆ nativeCapabilities()

Capabilities meshkit::nativeCapabilities ( )
constexpr

Feature flags of this native build.

Returns
A default-constructed Capabilities, in which every flag is true.

◆ read2dm()

ReadResult meshkit::read2dm ( const std::filesystem::path & path,
const IOOptions & options = {} )

Read an SMS 2DM file in two passes (nodes, then elements and node strings).

The path must name a seekable file that does not change between the passes (source_changed otherwise). Lines longer than Limits::maxRecordBytes fail. IDs must be positive and material IDs int32 unless IOOptions::legacy2dm; unsupported cards follow IOOptions::unknownRecords. Clockwise cells are reversed and counted; degenerate or nonconvex cells fail. A node string of more than two nodes whose last ID repeats its first becomes a closed path. The result has unknown units (Metadata::unitsKnown is false). Failures are returned in the report, not thrown.

Returns
The validated mesh with status Complete, or CompleteWithExceptions when cards were ignored; on failure an empty mesh and the failure status, code and message.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ readBinary() [1/2]

ReadResult meshkit::readBinary ( const std::filesystem::path & path,
const IOOptions & options = {} )

Open a file in binary mode and read it as MKB, as the stream overload does.

An empty path or one with an embedded NUL returns code path, and a file that cannot be opened returns open_input; both keep the default status Failed and an empty mesh.

Returns
The stream overload's result, or one of the failures above.
Here is the call graph for this function:

◆ readBinary() [2/2]

ReadResult meshkit::readBinary ( std::istream & stream,
const IOOptions & options = {} )

Read a version-1 MeshKit binary (MKB) mesh from a stream.

The stream (borrowed, binary mode, need not be seekable) is read in 64 KiB blocks through to its end: bytes after the checksum footer fail with trailing_data. The options supply the count, workspace, work and metadata-byte limits and the cancellation poll. Counts are checked against the limits before bulk allocation; the checksum and validateMesh() are checked last. Failures are returned in the report, not thrown (exceptions derived from std::exception, including allocation failure, are converted); the mesh is then empty.

Returns
The mesh and a report with status Complete, code read, vertex/triangle/quad counts, bytes consumed and the number of records read.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ resolutionRemovalImportance()

double meshkit::resolutionRemovalImportance ( double flatness,
double actualSize,
double targetSize )
inline

Rank a vertex for resolution-aware coarsening; lower values are tried first.

Parameters
[in]flatnessStar flatness: the smallest cosine between a facet normal and the star's summed normal, clamped to [-1, 1]; 1 is flat.
[in]actualSizeCurrent local cell size in XY units; positive and finite.
[in]targetSizePrescribed target size in the same units; positive and finite.
Returns
sqrt(2 * (1 - flatness)) * actualSize / targetSize, dimensionless and >= 0; +infinity when flatness is nonfinite or a size is not positive and finite.
Here is the caller graph for this function:

◆ runJob()

JobResult meshkit::runJob ( const JobRequest & original,
const Providers & providers = {},
EventChannel * events = nullptr )

Run one meshing job synchronously on the calling thread.

Checks the request, plans quad patches when requested, builds and refines the constrained Delaunay triangulation, assembles the mesh, validates it with validateMesh(), and audits constraints, sizes, transitions and terrain. When a planned patch interface does not conform, or (with strict sizing and quad patches present) a transition exceeds JobOptions::adjacentRatio, it retries with the region's spacing halved (required region), the region meshed as triangles (preferred region) or automatic blocks disabled, at most three times. Independent jobs may run on independent threads.

Parameters
[in]originalSource geometry and options; borrowed and only read during the call.
[in]providersCallbacks and identity; copied, and called only on this thread during the call.
[in,out]eventsOptional channel (may be nullptr) that receives Stage and Progress events, a Diagnostic event per retry and one final Completed event. A channel ignores events after Completed, so use a new one per job.
Returns
Owned result. Complete and CompleteWithExceptions deliver a mesh; Infeasible, Cancelled, ResourceLimit and Failed return an empty mesh and mapping with the report. Exceptions raised during an attempt, including from callbacks, are caught and reported.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ statusName()

const char * meshkit::statusName ( RunStatus status)
inlinenoexcept

Stable lower-case name of a status, as used by the Python bindings.

Parameters
[in]statusStatus to name.
Returns
Static string such as "complete" or "complete_with_exceptions"; "failed" for a value outside the enumeration. The caller must not free it.

◆ validateMesh()

OperationReport meshkit::validateMesh ( const Mesh & mesh,
const Limits & limits = {},
const std::function< bool()> & cancelled = {} )

Check a mesh's local validity without modifying it.

Checks, in order: counts against the limits, positive finite unit scales, UTF-8 metadata, unique label ids, id and marker array lengths, unique ids, finite coordinates, cells with 3 or 4 in-range corners forming a strictly convex counter-clockwise polygon (exact orientation tests), edges with distinct in-range endpoints, paths with a known kind and at least two in-range vertices, and in-range alias vertices. Metadata::unitsKnown, path closure, duplicate edges and overlap between non-adjacent cells are not checked. The first failure ends validation. Synchronous; nothing is retained after return.

Parameters
[in]meshMesh to check; borrowed and only read.
[in]limitsCaps on counts, metadata bytes and work units (default Limits{}).
[in]cancelledOptional callback, polled on entry and then every 4096 work units; returning true ends validation with RunStatus::Cancelled.
Returns
Report with status Complete, code "valid", the vertex/triangle/quad counts and the work used on success. Otherwise Infeasible for invalid data, ResourceLimit for an exceeded cap or failed allocation, Cancelled, or Failed (code "exception") for any other std::exception; never CompleteWithExceptions.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ write2dm()

IOReport meshkit::write2dm ( const std::filesystem::path & path,
const Mesh & m,
const IOOptions & options = {} )

Validate a mesh and atomically publish it to a path as SMS 2DM.

The mesh (borrowed, unchanged) must pass validateMesh(), have nodes and cells, and positive external node and element IDs. Cell regions become materials; paths become NS records (ten IDs per line, last ID negated, a closed path repeats its first node). Coordinates use 17 significant digits. Units/CRS/description, vertex markers, labels, aliases, edges and non-default path attributes cannot be written: they are refused (code attribute_loss) unless IOOptions::allowAttributeLoss. Publication follows writeBinary().

Returns
Status Complete (code written), or CompleteWithExceptions with the loss codes in IOReport::losses; otherwise the failure status, code and message.
Here is the call graph for this function:

◆ writeBinary()

IOReport meshkit::writeBinary ( const std::filesystem::path & path,
const Mesh & mesh,
const IOOptions & options = {} )

Validate a mesh and atomically publish it to a path as version-1 MKB.

The mesh (borrowed, unchanged) is checked by validateMesh() under the options' limits before any file is created. Records stream to an exclusive temporary file in the destination's directory, which is then published under the overwrite and durable options. Cancellation or failure removes the temporary and leaves any existing file unchanged. Failures are returned in the report, not thrown.

Returns
Status Complete with code written, bytes written and work used; otherwise the failure status, code and message.
Here is the call graph for this function:

Variable Documentation

◆ missingIndex

Index meshkit::missingIndex = ~Index(0)
constexpr

Sentinel index (all bits set, 4294967295) meaning "no index".

It is, for example, the default JobException::cell. A mesh must hold fewer vertices than this value; validateMesh() reports a larger vertex array as a resource limit.