SDK · crate

kinogaki-geometry

SDK

Kinogaki Studio's standard geometry values.

Repository
SDK (kinogaki/studio-sdk)
Folder
sdk/crates/geometry
Source
82 files, 18,941 lines
Tests
11 files, 2,986 lines
depends onused by tests alonedependencies for tests alone are listed below, not drawn

What it is

Kinogaki Studio's standard geometry values.

Studio defines each kind of geometry once, here, and every package works on the same values: kernels operate on them, formats read and write them, render engines draw them, and Studio displays, picks, tabulates and saves them. A kernel adds operations, never a type of its own for the same data.

ValueWhat
Geometrypolygons, polylines and curves over shared points: one Primitives table, each primitive of a Kind (Basis and closed), in any order, with Attributes; a primitive evaluates as a Curve
Brepboundary-representation bodies with exact geometry, free curves and datums (brep)
Image2D tiled layers over a data and a display window: files, textures, Comp's boundaries, the canvas (image)
Attributesnamed Attribute columns (an AttributeType: Storage × width × Meaning, arrays) and groups (Elements) per Domain; Text is indexed; standard names
Selection, Incidenceselected elements of one domain, with the active one; which elements of a value touch which (selection rules live in kinogaki-edit)
Triangulation, ShadingNormalshow polygons are shown: the one display triangulation and shading rule every viewport, engine and kernel shares
Detail, DisplayQualityhow fine geometry is made for a view or a render
Tolerancesthe project's modeling tolerances
Vec3, Xform, Bounds, Ray, Projectivethe one vector, placement (affine, column vectors), box, ray and view matrix every crate exchanges; Frame is an orthonormal frame
Units, Time, Rate, Sampledwhat a scene unit is; a moment on the tick grid and frames a second; a value across a frame's shutter
parallelthe process's shared Workers: every parallel step runs on what the host installed

Validated values. Every value's fields are private. It is made only through a constructor or builder that checks its rules (each type lists them) and refuses with an Error naming the element at fault, so code reading a value may rely on them: no invalid value can exist. An enum the SDK grows, whose values a reader meets without naming them all, is #[non_exhaustive] (its reader's wildcard says what it does with a variant added since); a closed set a match answers whole is exhaustive. ARCHITECTURE.md states the rule.

Shared and immutable. Arrays are Columns: shared cells that adopt a Vec without copying it. A value is never changed in place: an edit (with_moved, with_attributes, Attributes::with) makes a new value sharing every column and every cell it didn't touch, and checks only what it replaced. Geometry keep their primitives in one shared Arc<Primitives>, so moving points keeps the table, its edges and every cache built on it.

Product limits (limits): every element id fits a u32 (MAX_POINTS, MAX_PRIMITIVES, MAX_VERTICES: 2³² − 2 each) and names are at most 256 bytes. Every position component is finite and at most 1e100 in magnitude.

Caches derived from a standard value

A kernel or Studio may keep acceleration data (adjacency, half-edges, a triangulation, a BVH), but only as a cache derived from a standard value, never as the value itself:

  1. Keys. A cache is derived from one shared part of a value and is keyed by that part's identity: the Primitives for adjacency, edges, half-edges, triangulation and triangle maps; the positions Column for BVHs and bounds; an attribute's Column for anything built from that attribute.
  2. Where caches live. Use Primitives::derived and Column::derived (a viewport packet keeps its own Derived slots, for what is made from it). A slot lives exactly as long as its part and is shared by every value that shares the part, so a points-only edit (with_positions) keeps every table cache. Never keep a cache in a global map keyed by address.
  3. Readers. Only the crate that defines a cache's type reads it. A slot is never a channel between plugins.
  4. Never stored. A cache is never saved, compared or treated as the value. Dropping it may only cost time.
  5. Key lifetime. Column::key and ptr_eq are valid while the part lives, within one session. Use Primitives::fingerprint or a stamp for anything that outlives it.
  6. Independent caches. Two kernels' caches over one part are two slots, and neither sees the other's.

The canonical Index (Primitives::index) is the one cache this crate defines over a table: every kernel and Studio share its edges and numbering instead of building their own.

Depends on

None.

Third-party

CrateVersionLicenceFrozen inAsAlso used by
blake31.8.7CC0-1.0 OR Apache-2.0 OR Apache-2.0 WITH LLVM-exceptionlib-ui/vendornormalkinogaki-core-package, kinogaki-geometry-view, kinogaki-network, kinogaki-scene
bytemuck1.25.2Zlib OR Apache-2.0 OR MITlib-ui/vendornormalkinogaki-composit-wgpu, kinogaki-geometry-view, kinogaki-image-pipeline, kinogaki-math, kinogaki-pixel, kinogaki-ui, kinogaki-ui-wgpu, kinogaki-viewport-api and 2 more

Used by

CrateRepositoryAsWhat it is
kinogaki-editSDKnormalKinogaki Studio's edit contracts: what core and the kernels agree on when a value is selected and changed.
kinogaki-mtlxSDKnormalMaterialX 1.39 for Kinogaki Studio: the material layer every engine, format and core share, in our own implementation (MaterialX's C++ library is a reference and a test oracle, never a dependency).
kinogaki-render-apiSDKnormalKinogaki's render interface: what a host (Studio) sends a render engine and what comes back, with no GPU or OS API.
kinogaki-sharedCore and the appnormalThe crates Studio and its plugins share, built once as a Rust dylib.
kinogaki-studio-apiSDKnormalKinogaki Studio's headless plugin API.
kinogaki-studio-api-testingSDKnormalThe SDK's test support (a dev-dependency only): assert_refused for admission tests, read_hostile for a format's tests of hostile files, format for its scratch folders and round trips, workers as a host installs them, with wgpu an ...
kinogaki-valueSDKnormalKinogaki Studio's value model: the one way the SDK says what a value is and holds.
kinogaki-viewport-apiSDKnormalKinogaki's viewport packet contract: what a data type hands Studio's viewport to draw, with no GPU or UI API.
kinogaki-viewport-corelib-viewportnormalKinogaki viewport core: what a 3D viewport shows, independent of any GPU API or UI toolkit.
kinogaki-viewport-gpulib-viewportnormalKinogaki's wgpu viewport renderer: pipelines, retained GPU buffers, offscreen multisampled targets and owned WGSL shaders.

Modules

Public types and traits

At the crate root

Traits IncidenceTuple

Structs AcrossAttributeAttributesAttributeTypeBoundsColumnComponentsCurveCurveDataDerivedDiagnosticEdgeElementsErrorFrameGeometryIndexKindKnotsPrimitivesProjectiveRateRaySampledSelectionShadingNormalsSpanTableChangeTableWriterTextTextSpanTimeTolerancesTriangleTriangulationUnitsVec3WalkXform

Enums BasisDetailDisplayQualityDomainErrorKindMeaningSeverityStorageUpAxisValues

By module: 121 public types and traits in 55 modules

across Across

attributes Attributes

attributes::attribute AttributeTupleValues

attributes::domain Domain

attributes::text Text

attributes::types AttributeTypeMeaningStorage

bounds Bounds

brep BrepDatumDatumHintDatumKind

brep::body Body

brep::builder BrepBuilderCoedgeSpecEdgeSpecFaceSpec

brep::geometry Geometry

brep::geometry::curves CircleCurveEllipseLine

brep::geometry::pcurves Circle2Ellipse2Line2PCurve

brep::geometry::surfaces ConeCylinderExtrusionOffsetPlaneRevolutionSphereSurfaceTorus

brep::names NameNameNodeOperationId

brep::numbering Element

brep::nurbs NurbsCurveNurbsSurfaceSeamContinuity

brep::topology BodyKindBrepTopologyCoedgeCountsEdgeFaceLoopNamesSenseShellVertex

column Column

curve CurveSpan

derived Derived

detail DetailDisplayQuality

diagnostic DiagnosticSeverityTextSpan

elements Elements

error ErrorErrorKind

frame Frame

geometry Geometry

image FormatImageImageBuilderLayerRectTileWeakImage

image::encoding ColorTagEncoding

image::held HeldPixels

image::pyramid Pyramid

image::sample Sample

image::sampler SampleFilterSampler

image::sampling FilterSamplingWrap

image::source EmbeddedFileImageColorImageFileImageSource

incidence Incidence

nearest HitSpotsSurface

parallel Workers

primitives EdgePrimitives

primitives::changes TableChange

primitives::components Components

primitives::curves CurveDataKnots

primitives::index Index

primitives::index::walk Walk

primitives::kind BasisKind

primitives::writer TableWriter

sampled Sampled

selection Selection

shading ShadingNormals

time RateTime

tolerances Tolerances

triangulation TriangleTriangulation

units UnitsUpAxis

vec3 RayVec3

xform ProjectiveXform

Besides these, 5 public functions at module level.