1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
//! GEOMETRY: the shapes an analyzer reports a FINDING'S LOCATION as, and the one coordinate this
//! crate names to measure them in.
//!
//! # It is a FAMILY, and it is the first here that is DOMAIN-NEUTRAL
//!
//! [`lang`](super::lang) arrived as a family because a STANDARD does not come one type at a time,
//! and [`mediatime`](super::mediatime) because a tick count is not a time until a timebase says what
//! a tick is. This house arrives as one for a third reason: a point, a rectangle and a quadrilateral
//! are ONE geometry read at three arities, they share a component and an origin convention, and a
//! caller that has any of them has the others within a frame.
//!
//! Nothing here knows what a box is a box OF. A face detection, a text line, a saliency region, a
//! table cell on a scanned page and a subject mask's extent are five callers with one rectangle
//! between them, and the composite that pairs one of these with a label and a confidence is NOT this
//! module's — it is [`detect`](super::detect)'s, one door over, which consumes these. That split is
//! what makes the house domain-neutral rather than a vision library with the vision taken out: the
//! types below would be the same types for a PDF's glyph boxes, which have no detector and no score
//! anywhere near them.
//!
//! **The pairing landed BESIDE this house rather than downstream of it**, and the sentence that
//! stood here said otherwise — *they belong to the crate that has the labels*. The ruling that sent
//! the geometry cluster here sent the classification trio after it on the same ground: a label and a
//! confidence are no more a camera's than a rectangle is. What stayed downstream is the layer above
//! both — the poses, the masks and the landmark contours, which are a producer's vocabulary rather
//! than a shape. See [`detect`](super::detect), where that line is drawn from the other side.
//!
//! # GENERIC over the component, and the parameter is the ruling
//!
//! [`Point2<T>`], [`BoundingBox<T>`] and [`Quad<T>`] are DUMB HOLDERS over whatever a declaration
//! measures in. **Not everyone wants a normalized coordinate** — a metric pipeline measures in
//! `f64` metres, a raster one in `u32` pixels, a quantised model in a half-width float — and a
//! holder that admitted one of those and refused the rest would be a holder with an opinion about a
//! unit it was never told.
//!
//! [`NormCoord`] is the ONE instantiation this crate names, and it is named because the normalized
//! frame is the one world with a rule that is not the caller's: a coordinate in `[0.0, 1.0]` is a
//! fraction of a frame whatever the frame is. Every other `T` a caller brings is admitted without
//! being enumerated — the openness is the holders', and a roster of blessed widths would be exactly
//! the closed surface this framework does not build.
//!
//! # WHERE AN INVARIANT LIVES: on the component, or on ONE instantiation's impl block
//!
//! The rule this house is arranged by, and it is worth stating once because it decides every
//! question below it:
//!
//! - **A rule about ONE NUMBER lives on the component.** Finite, and inside `[0.0, 1.0]` — that is
//! [`NormCoord::new`], and every holder gets it for free by holding one. An invalid value dies at
//! the component's constructor and never reaches a shape.
//! - **A rule about a SHAPE IN A UNIT FRAME lives on that shape's `BoundingBox<NormCoord>` impl
//! block, and nowhere else.** A strictly positive extent, and an edge that does not run past
//! `1.0`, are true of a normalized rectangle and meaningless for a metric or a pixel one. So
//! [`BoundingBox::try_unit`] is where they are checked, and `BoundingBox::new` — the generic
//! constructor — checks nothing at all.
//!
//! A generic *is this degenerate* helper was considered and declined. It would need `T: PartialOrd`
//! plus a ZERO, and the zero is what still refuses it: a bound naming a distinguished value is a
//! numeric vocabulary this crate does not own, where a bound naming an OPERATOR is std's. When in
//! doubt the check stays on the specific impl, which is where it is true.
//!
//! # THE READINGS, and the arithmetic bound each one costs
//!
//! Two methods here compute rather than return, and each states its own bound at its own signature —
//! the arrangement [`rust-bound-minimization`'s fixpoint asks for][area] and the one every accessor
//! in this house already takes.
//!
//! | reading | bound | who is in |
//! |---|---|---|
//! | [`BoundingBox::area`] | `T: Copy + Mul<Output = T>` | [`NormCoord`], `f32`, `f64`, integer widths, any component with the operator |
//! | [`Quad::bounds`] | `T: Copy + PartialOrd + Sub<Output = T>` | `f32`, `f64`, integer widths — and NOT [`NormCoord`] |
//!
//! **The asymmetry is a census verdict rather than an oversight.** The closed unit interval is
//! closed under MULTIPLICATION — a product of two values in `[0, 1]` is in `[0, 1]` at every width —
//! and it is NOT closed under subtraction, `0.2 - 0.8` being `-0.6`. So the coordinate publishes the
//! one operator that is total on it and not the one that is not, and the box a normalized quad
//! reduces to is out of bounds rather than refused: closing it would mean an operator that
//! saturates, clamps or panics on the values its own domain excludes, which is the *value quietly
//! minted around the hole* the decode below refuses.
//!
//! [area]: BoundingBox::area
//!
//! # TOP-LEFT ORIGIN, and `xywh`
//!
//! `y` grows DOWNWARD and a rectangle is its top-left corner plus two extents. `avanalyze` — the
//! producer this framework has actually met — flips Vision's bottom-left normalized rectangles onto
//! that convention before a value is ever built, and states that bounding boxes, 2-D pose joints,
//! face landmarks and document quads all share it. A second convention here would be a translation
//! layer standing between this crate and every caller it has.
//!
//! A [`Quad`]'s corners are in PERIMETER WINDING ORDER — top-left, top-right, bottom-right,
//! bottom-left. That is the same producer's `DocumentSegment` contract, whose own note says what
//! reading them as `(TL, TR, BL, BR)` costs: *an implementation that reads them as `(TL, TR, BL,
//! BR)` builds a bow-tie out of every real document*. The order is pinned by a test here for the
//! same reason it is pinned by a conformance suite there.
//!
//! # A SECOND, INDEPENDENT CITIZEN: [`Radians<T>`](Radians)
//!
//! Everything above is the POSITION half of this house — a point, a rectangle, a quadrilateral, and
//! the one coordinate they are generic over. [`Radians<T>`](Radians) is the other neutral quantity a
//! producer's geometry needs and names nothing about a place: a face's roll, yaw and pitch, a
//! horizon's tilt. It shares this module for [`NormCoord`]'s own reason — a producer that has a
//! normalized frame typically has an angle beside it, and neither is anyone's business but this
//! crate's own numbers — and it is GENERIC over its carrier for the same reason
//! [`BoundingBox<T>`](BoundingBox) is: not everyone measures an angle in the same width, and a holder
//! with an opinion about one is a holder that was never asked.
//!
//! It is not a fourth arity of [`Point2`]/[`BoundingBox`]/[`Quad`]'s shared parameter — it holds ONE
//! `T` rather than fanning one out into several columns, so it carries none of their fixed-arity
//! machinery — and it carries no interval the way [`NormCoord`] does; see the type's own note for the
//! census that keeps the two apart. Its faces are FULLER than [`NormCoord`]'s own — a mongo carrier
//! and a GraphQL filter under its own name — because it is reachable as a bare, top-level column a
//! declaration names directly (a face's `roll: Option<Radians<f32>>`), where every holder's own
//! component today is reached only nested inside one of the three shapes above.
//!
//! # THE GATE: none, and the reason is the dependency law read where it runs out
//!
//! Every other vocabulary door in this crate is named for the DEPENDENCY it admits — `mediatime`
//! for the crate whose four types that family wraps, `half` for a width somebody else ships. **This
//! house has no dependency at all**: the types are this crate's own, over Rust's own numbers, and
//! the whole module is arithmetic and column names.
//!
//! So it is UNGATED, and the precedent is exact rather than argued from silence.
//! [`TimeRange`](crate::TimeRange) and [`TimeRanged<T>`](crate::TimeRanged) are a dependency-free,
//! GENERIC primitives family whose filter is HAND-WRITTEN, and they carry no word of their own;
//! [`Confidence`](crate::Confidence), [`Count`](crate::Count) and [`Timestamp`](crate::Timestamp)
//! are ungated beside them. The one dep-free family that DOES ride a word is
//! [`lang`](super::lang), and it rides `derive` because two of its five filters are DECLARED — a
//! tier it needs rather than a dependency it admits.
//!
//! **This house needs no tier either**, and that is a measurement rather than a preference: the
//! `#[ingraph(composed)]` derive takes a CONCRETE struct, so the three filters below — every one of
//! them generic over the component's filter — could not be declared through it whatever this module
//! wanted. They are hand-written on [`TimeRangedFilter`](crate::TimeRangedFilter)'s own road, and a
//! build that declines the declaration tier keeps every one of them.
//!
//! Each FACE beneath the family carries its own cross-gate, as every family here does: `sqlx` for
//! the binds and decodes, `async-graphql` for the wire.
//!
//! # The three layers, and the one crossing between them
//!
//! ```text
//! domain crossing storage
//! NormCoord identity f32
//! Point2<T> per component (T, T)
//! BoundingBox<T> per component (T, T, T, T) + a DERIVED T
//! Quad<T> per component (T, T) × 4
//! ```
//!
//! Every crossing is the COMPONENT's, applied per column, and no VALUE here is reduced or
//! canonicalised — which is why none of these types has an `exact` facet: a value that crosses
//! unchanged has one identity, and the leaf tuple is it.
//!
//! **ONE type carries a fifth column that is not part of its value.** `BoundingBox<T>` stores its
//! `area` — `width × height`, written by the bind and read by no decode — because *how much of the
//! picture is this* is the one question about a rectangle that is a single ordered number, and
//! asking it over the stored pair is an expression no index can serve. It is a DERIVED LEAF in the
//! sense [`ColumnShape`](crate::ColumnShape) rules: it serves the semantic filter alone, and every
//! structural judgment in the crate — the decode, an optional box's `None` test, a row-value
//! equality, a cursor — walks the four value leaves and never it. See [`BoundingBox`]'s own segment
//! note, where the whole ledger is written out, and its `ORDER`, where the derived leaf is
//! deliberately in no level at all.
//!
//! # What a DECODE can and cannot re-prove
//!
//! A read goes through the COMPONENT's constructor, so a stored number outside `[0.0, 1.0]` in a
//! `NormCoord` column is refused at the column that held it. That is the whole of what the type
//! system can re-establish from four independent columns.
//!
//! **The SUM rule is not re-checked on the way in, and the gap is recorded rather than papered
//! over.** A hand-written `UPDATE` can leave `x = 0.9, width = 0.5` — two valid coordinates whose
//! sum leaves the frame — and the decode will hand back a `BoundingBox<NormCoord>` that
//! [`try_unit`](BoundingBox::try_unit) would have refused. Closing it means a refusal in
//! [`Assemble`](crate::Assemble) for ONE instantiation of a generic row, which stable Rust cannot
//! spell — a specialised impl is what it would take — so the honest posture is to say where the
//! promise stops. `try_unit` is a CONSTRUCTOR's guarantee, not a column constraint, and a database
//! that wants one writes a `CHECK` this crate does not emit.
//!
//! # The wire faces
//!
//! Behind `async-graphql`: the three holders as GraphQL OBJECTS whose names COMPOSE from the
//! component's own — `BoundingBoxF32`, `Point2F32`, `QuadF32` for the normalized world, since a
//! coordinate publishes its width's roster scalar — and one input object per filter beside them.
//! The composition is not decoration: GraphQL keeps ONE FLAT NAMESPACE, so a schema holding a
//! metric box and a normalized one needs two names, and a single `BoundingBox` would be a name
//! async-graphql resolves in silence.
//!
//! There is no operand SCALAR anywhere in this house. A holder publishes an object and takes no
//! whole-value operand — see [`BoundingBoxFilter`], where the absence is argued — and
//! [`NormCoord`] publishes `f32`'s own roster scalar rather than a named one, on the ruling that
//! retired [`Score`](crate::Score)'s: a named scalar has to say something the roster does not, and
//! what a `NormCoord` scalar would have said is the INTERVAL, which is a constructor's promise
//! rather than a grammar.
// The SQL side for all three, in ONE file for the wire faces' reason: three comparisons that are
// one lowering shape at three arities, read side by side.
// The wire faces for all three holders and all three filters in ONE file, where every other family
// here splits them per citizen. The shape is the reason: the three faces are one pattern at three
// arities — a composed name, an object of components, an input object of facets — and reading them
// side by side is what makes a divergence between them visible.
// The house's SECOND independent citizen, beside `coord` rather than under it: an angle shares this
// module's dependency-free, tier-free gate for the same reason `NormCoord` does — the type is this
// crate's own, over Rust's own numbers, with every face self-contained in its own file on this
// family's own convention. See the type's own note for why it carries no interval, why its faces are
// fuller than `NormCoord`'s own (a mongo carrier and a named filter, which no holder here has needed
// yet), and why — unlike the three composites above — it needs no leaf guard to stay honest about a
// generic carrier.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;