Skip to main content

indicatrix_cut_core/
lib.rs

1//! `indicatrix-cut-core` is the editor-core library for a faceting-design editor: it owns the
2//! preform, the editable cutting instructions, undo/redo, and live-solid validation --
3//! everything a UI needs to answer "what does this schedule look like right now,
4//! and is it a real stone" without itself touching a window, a database, or a
5//! renderer.
6//!
7//! # Why this is a separate crate from the GUI
8//!
9//! Undo/redo is business logic, not view logic: it has to be correct independent of
10//! whatever widget toolkit drives it, and testable without a window (see [`edit`]'s
11//! module doc comment). Two dependencies only -- [`indicatrix`] for geometry and
12//! [`indicatrix-formats`] for `.asc` read/write and the `.isdd` design file's own
13//! on-disk format -- so `apps/indicatrix-cut` can wire a UI on top of it without this
14//! crate ever needing to know Slint, wgpu, or SQLite exist.
15//!
16//! # The pieces
17//!
18//! - [`preform`]: the physical rough a design's facets are cut from -- always a
19//!   closed plane set, so a brand-new design already renders as a real solid.
20//! - [`design`]: [`design::Design`] pairs a [`preform::PreformSpec`] with
21//!   [`design::ConstraintTier`]s -- authored meet constraints, not recorded masts.
22//!   `Design::solve` derives masts on demand and builds the full plane arrangement
23//!   feeding `indicatrix::geometry::stone_metrics::build_solid_mesh`.
24//! - [`edit`]: [`edit::Edit`] (add/remove/modify a tier or its constraint, or
25//!   replace the preform) and [`edit::History`], a command/inverse-pair undo/redo
26//!   stack over a [`Design`].
27//! - [`resolve`]: [`resolve::resolve_after_edit`] re-solves only the tiers an edit
28//!   could actually change, instead of [`Design::solve`]'s whole-design re-solve.
29//! - [`orbit`]: [`orbit::orbit_units`] derives a tier's symmetry-generated facet
30//!   groups from schedule metadata (never stored, always recomputed), and the
31//!   `Design::*_orbit_member` helpers keep membership changes orbit-consistent by
32//!   construction.
33//! - [`manufacturability`]: four checks (vanishing facets, undersized facets,
34//!   gear-quantization error, out-of-order meets) over an already-solved
35//!   [`design::Design`] -- warnings only, never silently corrected.
36//! - [`material`]: [`material::MaterialSelection`] and a specific-gravity lookup
37//!   table; [`material::MaterialSelection::resolve`] and
38//!   [`design::Design::effective_refractive_index`] give a design one real
39//!   refractive index every consumer can derive from.
40//! - [`optics_hints`]: pure critical-angle math shared by the material-retarget
41//!   path and the solid preview's risk overlay.
42//! - [`yield_metrics`]: the real-unit binding ([`yield_metrics::mm_per_unit`]) and
43//!   the figures built on it -- exact volumetric yield, an estimated carat weight,
44//!   and the design-bigger-than-its-rough check.
45//! - [`native`]: converts a [`Design`] to and from the self-contained `.isdd`
46//!   design file (design state `.asc` has no field for at all; files saved as
47//!   `.indicatrix` before are read the same way), and builds the catalogue `.asc` text
48//!   a save stores next to it ([`native::catalogue_asc`]). The on-disk document itself --
49//!   schema, TOML encode/decode, path rules -- lives in
50//!   `indicatrix_formats::native`; this module owns only the conversions to and from
51//!   [`Design`].
52//! - [`optimize`]: the objective ([`optimize::evaluate_objective`]) and
53//!   [`optimize::optimize_design`], a deterministic coordinate search over a
54//!   design's free facet angles that never moves a pinned tier, never proposes
55//!   geometry that fails to close, and never regresses a manufacturability warning.
56//! - [`cutting_sheet`]: [`design::Design::cutting_sheet`] builds a
57//!   [`cutting_sheet::CuttingSheet`] (every tier in cutting order, with angle,
58//!   indices, solved mast and a printable meet instruction) from a design and
59//!   its already-solved masts; [`design::Design::facet_meets`] and
60//!   [`cutting_sheet::diff_tiers`] are the companion per-facet and
61//!   before/after reads built alongside it.
62//!
63//! # Determinism
64//!
65//! Every public operation here is a plain, total-order computation over the
66//! caller-supplied schedule/preform -- no `HashMap`/`HashSet` in any decision path, no
67//! wall-clock or thread-count dependence: two runs over identical input produce
68//! byte-identical output. [`optimize::optimize_design`] is the one place this crate
69//! takes a seed at all -- identical seed, identical result, always caller-supplied,
70//! never derived from wall-clock time.
71
72/// [`design::Design::cutting_sheet`]'s own output type.
73///
74/// [`cutting_sheet::CuttingSheet`]: every tier in cutting order, with angle,
75/// indices, solved mast and a printable meet instruction) plus the
76/// before/after diff over it ([`cutting_sheet::diff_tiers`]).
77pub mod cutting_sheet;
78/// A design's preform plus editable cutting instructions.
79///
80/// The derivation from authored constraints down to a renderable solid --
81/// see this module's own doc comment ("Constraints, not masts"/ "Scale
82/// anchoring").
83pub mod design;
84/// Reversible edits over a [`design::Design`].
85///
86/// [`edit::Edit`]/[`edit::History`]: the command/inverse-pair undo/redo
87/// stack built on them.
88pub mod edit;
89/// Warnings-only checks over an already-solved [`design::Design`].
90///
91/// Vanishing/undersized facets, gear-quantization error, out-of-order meets.
92pub mod manufacturability;
93/// A design's material choice and the specific-gravity lookup table.
94///
95/// [`material::MaterialSelection`] and the built-in refractive-index/specific-
96/// gravity lookup tables a design resolves its optics against.
97pub mod material;
98/// Shared hard preservation gate for planar optimization and material Retarget.
99///
100/// See the module's own documentation for the preservation contract.
101pub mod meet_preservation;
102/// The `.isdd` design file's conversions, plus the catalogue `.asc` text a save stores
103/// next to it.
104///
105/// See this module's own doc comment for the split with
106/// `indicatrix_formats::native`.
107pub mod native;
108/// Pure critical-angle math shared by several consumers.
109///
110/// The material-retarget path and the solid preview's risk overlay.
111pub mod optics_hints;
112/// A deterministic coordinate search over a design's free facet angles.
113///
114/// The objective ([`optimize::evaluate_objective`]) and
115/// [`optimize::optimize_design`] itself.
116pub mod optimize;
117/// Derives a tier's symmetry-generated facet groups from schedule metadata.
118///
119/// The `Design::*_orbit_member` helpers keep membership changes
120/// orbit-consistent by construction.
121pub mod orbit;
122/// The physical rough a design's facets are cut from.
123///
124/// Always a closed plane set, so a brand-new design already renders as a
125/// real solid.
126pub mod preform;
127/// Shape/material classification for the proportion-verdict windows.
128///
129/// The windows a solved design's measurements are judged against.
130pub mod proportions_windows;
131/// Re-solves only the tiers an edit could actually change.
132///
133/// [`resolve::resolve_after_edit`], instead of
134/// [`design::Design::solve`]'s whole-design re-solve.
135pub mod resolve;
136/// Plans how many stones of which designs fit one rough block.
137///
138/// [`rough_plan::plan_rough`]: staged guillotine cuts (six cut orders), a
139/// mixed-design DP over a shared piece table, single-design layouts and a
140/// continuous refinement of the cut positions, ranked by finished volume.
141pub mod rough_plan;
142/// The built-in "New Design" template gallery.
143///
144/// See this module's own doc comment for the `ScaleReference`-only
145/// restriction every entry follows.
146pub mod templates;
147/// The real-unit binding and the figures built on it.
148///
149/// [`yield_metrics::mm_per_unit`]: exact volumetric yield, an estimated
150/// carat weight, and the design-bigger-than-its-rough check.
151pub mod yield_metrics;
152
153pub use cutting_sheet::{
154    ConcaveRowInfo, ConcaveTierDelta, CutSheetRow, CuttingSheet, SHEET_NAME_WIDTH, TierDelta,
155    diff_concave_tiers, diff_tiers, format_sheet_index, format_sheet_indices,
156};
157pub use design::{
158    ConstraintTier, Design, DesignSolveError, DesignTierCodes, FreshDesignSpec, MissingAnchor,
159    ScheduleMeta, SolveMismatch, StoneRenderEffects, TargetResolveError, TierFrosting, TierId,
160    TierLabelInfo, TierTarget, compute_tier_labels, convert_legacy_facet_name, is_legacy_123_abc,
161    name_indicates_pavilion,
162};
163pub use edit::{
164    Edit, EditError, History, HistoryEntry, JumpError, RemapRounding, ScheduleState, remap_ratio,
165};
166pub use manufacturability::{
167    DEFAULT_MIN_FACET_AREA_FRACTION_OF_W2, ManufacturabilityWarning, check_manufacturability,
168    degenerate_suspects,
169};
170pub use material::{
171    BuiltinMaterials, MaterialCatalogue, MaterialEntry, MaterialKind, MaterialLookup,
172    MaterialSelection, ResolvedMaterial, SpecificGravity, built_in_refractive_index,
173    built_in_specific_gravity,
174};
175pub use native::{CatalogueAsc, SaveError, catalogue_asc};
176pub use optics_hints::{
177    Risk, critical_angle_deg, crown_window_margin_deg, crown_windowing_risk, retarget_angle_deg,
178    tier_margin_deg, windowing_risk,
179};
180pub use optimize::{
181    AngleChange, CANONICAL_LIGHTING_PRESET, FaceUpTone, MastChange, ObjectiveComponents,
182    ObjectiveFidelity, ObjectivePreset, ObjectiveWeights, OptimizeCandidate, OptimizeConfig,
183    OptimizeOptions, OptimizeOutcome, OptimizeResult, SearchHooks, ShapeTarget, ToneGoal,
184    apply_optimize_candidate, apply_optimize_outcome, apply_optimize_result, evaluate_objective,
185    evaluate_objective_geom_under, evaluate_objective_geom_under_threaded,
186    evaluate_objective_threaded, evaluate_objective_under, evaluate_objective_under_threaded,
187    evaluate_objective_with_tone, evaluate_objective_with_tone_geom_under_threaded,
188    evaluate_objective_with_tone_under, evaluate_objective_with_tone_under_threaded,
189    free_tier_indices, free_tier_indices_with, optimize_design, optimize_design_with,
190};
191pub use orbit::{OrbitUnit, expected_orbit, mirror_indices, orbit_units, rotate_indices};
192pub use preform::{PlaneSet, PreformShape, PreformSpec};
193pub use proportions_windows::{MaterialClass, Metric as ProportionMetric, ShapeClass, Verdict};
194pub use resolve::resolve_after_edit;
195pub use yield_metrics::{
196    PreformFit, StoneProportions, YieldReport, carat_weight, exceeds_preform, mm_per_unit,
197    volume_mm3, volumetric_yield,
198};