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};