Relative Percentile Culling & Safety Overrides
Mathematical distribution culling algorithm with absolute quality overrides in photo-rating-utils.
Relative vs. Absolute Culling
Traditional culling tools use fixed static quality cutoffs (e.g., "Keep all photos above 70%"). In difficult shooting environments (such as dimly lit reception halls or rainy outdoor games), this approach either rejects entire key moments or accepts too many mediocre frames.
BestShots implements a dynamic hybrid relative percentile model located in packages/shared/src/photo-rating-utils.ts.
Star Rating Percentile Boundaries
Photos within a project are ranked relative to the quality distribution of the entire session:
| Star Rating | Percentile Boundary | Description |
|---|---|---|
| 5 Stars | Top 15% (>= 85th percentile) | Master keepers, portfolio contenders, and hero burst winners. |
| 4 Stars | Top 45% (55th–84th percentile) | Strong story-supporting frames and secondary selections. |
| 3 Stars | Middle Tier (25th–54th percentile) | Acceptable documentary coverage. |
| 2 Stars | Lower Tier (10th–24th percentile) | Marginal quality, soft focus, or duplicate expressions. |
| 1 Star | Bottom 10% (< 10th percentile) | Definite discards, severe motion blur, closed eyes. |
Absolute Safety Overrides
To protect against mathematical anomalies where great photos might be suppressed in an exceptionally sharp shoot (or bad photos promoted in a poor shoot), the engine enforces absolute boundary overrides:
- Excellent Override (
excellentOverride = 90): Any photo scoring 90 points or higher is unconditionally awarded 5 stars, regardless of its relative percentile ranking. - Poor Override (
poorOverride = 35): Any photo scoring below 35 points is unconditionally restricted to 1 star / Discard, even if it happens to be the best frame in a degraded sequence.