indicatrix-cut 0.7.1

//! The extents and convex hull scan: measures candidate designs whose solid extents or
//! hulls are not in the catalogue database yet and saves each result as it lands.
//!
//! # The measuring rule
//!
//! `gui::editor::resolve_catalogue_planes` gives a design's planes and where they came
//! from:
//!
//! - A design file's planes are the preform's own planes FIRST, then the facet planes.
//!   The default preform is a generous cylinder, so a schedule that does not close on
//!   its own would measure as a fat, inflated blob. So only `planes[preform_plane_count..]`
//!   (the facet planes alone) are measured. If they close, the design is stored as
//!   `DesignFile` along with its convex hull vertices; if not, it relies on its preform
//!   to close and is stored as `Unbounded` with no extents or hull.
//! - A design's concave tiers (curved-tool cuts) only ever remove material from the facet
//!   stone, so the carved stone's outline is never larger than the flat one. A design WITH
//!   tools is measured from its CARVED mesh (`build_solid_mesh_geom(..)`): `volume` is the
//!   carved volume, and the vertices of the carved mesh are reduced to their convex hull
//!   (`shape::hull::design_outline`, the rough planner's own incremental hull), which gives
//!   the stored hull corners and the caliper extents (width, length, height). A tool that
//!   removes a vertex setting the outline therefore lets the planner place the stone
//!   tighter; a groove or dimple inside the outline changes nothing. Only the reduced hull
//!   corners are stored, never the raw mesh vertices, so the fit stage stays as fast as for
//!   a planar design. A design WITHOUT tools is measured from the flat facet planes exactly
//!   as before, bit for bit. The tools are resolved against the facet stone
//!   (`Design::facet_geometry_from_solved`), so the preform never moves them. Tools that
//!   remove the whole stone leave nothing to measure: the design counts as unmeasurable,
//!   like one that does not close. A design
//!   whose concave tiers cannot be resolved is not measured at all (see
//!   [`Loaded::ConcaveUnresolved`]): planning it as a flat stone would overstate its
//!   yield and carat.
//! - The angle-table fallback's planes are synthetic, so they are measured as they are
//!   and stored as `AngleTable` with no hull; the planner excludes them. (The angle table
//!   has no concave rows.)
//!
//! A design that cannot be loaded or panics while measuring is left unsaved, so the
//! next run tries it again.
//!
//! A measurement is stored only while the design's geometry is the one it was measured
//! from: the invalidation epoch of the database is read in the same lock hold as the
//! record, and the save is refused when the epoch moved (an import or a native save
//! replaced the geometry meanwhile). A measurement whose save FAILED is not lost: it is
//! handed back in [`ScanOutcome::measured`] for this run to plan with.

use super::{Reporter, WORKER_STACK_BYTES, group_thousands, panic_message, stages};
use crate::gui::{batch::batch_queue::local_lane_count, editor::CataloguePlanesSource};
use glam::DVec3;
use indicatrix::geometry::{
    GpuFacetPlane,
    stone_metrics::{
        SolidMetrics, SolidStatus, build_solid_mesh_geom, measure_solid_with_vertices, mesh_volume,
    },
    tool::ToolPrimitive,
};
use indicatrix_cut_core::rough_plan::shape::hull::design_outline;
use indicatrix_vault::{
    db::sqlite::Database,
    model::{
        entry::FullDiagramRecord,
        solid_extents::{SolidExtents, SolidExtentsSource, StoredSolidExtents},
        solid_hull::SolidHull,
    },
};
use std::{
    collections::BTreeMap,
    panic::{AssertUnwindSafe, catch_unwind},
    sync::{
        Mutex, PoisonError,
        atomic::{AtomicUsize, Ordering},
    },
    time::{SystemTime, UNIX_EPOCH},
};
use tracing::{debug, warn};

/// The share of the progress bar the scan occupies when it has anything to do; the
/// planning stages use the rest.
pub(super) const SCAN_BAND: f32 = 0.35;

/// A design's measured extents, its source classification, and optional convex hull.
type Measured = (Option<SolidExtents>, SolidExtentsSource, Option<SolidHull>);

/// `metrics` as the stored extents, or `None` if any figure is unusable.
fn extents_of(metrics: &SolidMetrics) -> Option<SolidExtents> {
    let extents = SolidExtents {
        width_caliper: metrics.width_caliper,
        length_caliper: metrics.length_caliper,
        width_axis: metrics.width_axis,
        length_axis: metrics.length_axis,
        height: metrics.total_height,
        volume: metrics.volume,
    };
    [
        extents.width_caliper,
        extents.length_caliper,
        extents.width_axis,
        extents.length_axis,
        extents.height,
        extents.volume,
    ]
    .iter()
    .all(|v| v.is_finite() && *v > 0.0)
    .then_some(extents)
}

/// What measuring one record came to.
pub(super) enum Measurement {
    /// The figures, stored or planned with as they are.
    Done(Measured),
    /// The design's concave tiers could not be resolved, so its stone is unknown. Not
    /// measured and not saved (a later run tries again); carries the reason.
    ConcaveUnresolved(String),
}

/// Measures one record under the rule in this module's doc comment.
pub(super) fn measure_record(full: &FullDiagramRecord) -> Measurement {
    let resolved = crate::gui::editor::resolve_catalogue_planes(full);
    if let Some(reason) = resolved.concave_error {
        return Measurement::ConcaveUnresolved(reason);
    }
    Measurement::Done(measure_planes(
        resolved.source,
        resolved.preform_plane_count,
        &resolved.planes,
        &resolved.tools,
    ))
}

/// The volume of the stone bounded by `facets` after `tools` have cut it and the corners of
/// its carved mesh, or `None` when the carved stone is not a closed solid (the tools removed
/// all of it). Without tools this is not consulted, so a planar design keeps the figures
/// `measure_solid_with_vertices` gave it, bit for bit.
fn carved_stone(facets: &[(DVec3, f64)], tools: &[ToolPrimitive]) -> Option<(f64, Vec<DVec3>)> {
    match build_solid_mesh_geom(facets, tools) {
        SolidStatus::Closed(mesh) => {
            let corners = mesh
                .rings
                .iter()
                .flat_map(|(_, ring)| ring.iter().copied())
                .collect();
            Some((mesh_volume(&mesh), corners))
        }
        _ => None,
    }
}

/// `metrics` and `verts` of the flat facet stone, replaced by the carved stone's: the
/// volume of the carved solid, and the width, length and height of the convex hull of its
/// vertices (a tool that removes a vertex setting the outline makes the stone smaller, so
/// the planner may place it tighter). `verts` becomes that hull's corners, the only points
/// the fit stage sees. `None` when the tools remove the whole stone. Unchanged without
/// tools. If the carved vertices have no hull the flat outline is kept: it is the larger
/// one, so a planned stone still fits.
fn carve(
    metrics: SolidMetrics,
    verts: Vec<DVec3>,
    facets: &[(DVec3, f64)],
    tools: &[ToolPrimitive],
) -> Option<(SolidMetrics, Vec<DVec3>)> {
    if tools.is_empty() {
        return Some((metrics, verts));
    }
    let (volume, mesh_corners) = carved_stone(facets, tools)?;
    let Some(outline) = design_outline(&mesh_corners) else {
        return Some((SolidMetrics { volume, ..metrics }, verts));
    };
    let extents = outline.extents;
    let carved = SolidMetrics {
        volume,
        width_caliper: extents.width_caliper,
        length_caliper: extents.length_caliper,
        width_axis: extents.width_axis,
        length_axis: extents.length_axis,
        total_height: extents.height,
        vertex_count: outline.corners.len(),
        ..metrics
    };
    Some((carved, outline.corners))
}

/// Measures `planes` (in the tracer's `n . x + d <= 0` convention) that came from `source`;
/// the first `preform_plane_count` of a design file's planes are its preform and are left
/// out. `tools` are the design's concave tools on the facet stone (empty for a planar one
/// or the angle table); they reduce the volume only.
fn measure_planes(
    source: CataloguePlanesSource,
    preform_plane_count: usize,
    planes: &[GpuFacetPlane],
    tools: &[ToolPrimitive],
) -> Measured {
    let halfspaces: Vec<_> = planes
        .iter()
        .copied()
        .map(GpuFacetPlane::to_halfspace_f64)
        .collect();

    match source {
        CataloguePlanesSource::AngleTable => {
            let measured = measure_solid_with_vertices(&halfspaces);
            let extents = measured.as_ref().and_then(|(m, _)| extents_of(m));
            (extents, SolidExtentsSource::AngleTable, None)
        }
        CataloguePlanesSource::DesignFile => {
            let start = preform_plane_count.min(halfspaces.len());
            let facets = &halfspaces[start..];
            // `None` when the facets do not close or the tools remove everything.
            let measured = measure_solid_with_vertices(facets)
                .and_then(|(metrics, verts)| carve(metrics, verts, facets, tools));
            match measured {
                Some((metrics, verts)) => {
                    let extents = extents_of(&metrics);
                    let vertices = verts
                        .into_iter()
                        .map(|v| [v.x as f32, v.y as f32, v.z as f32])
                        .collect();
                    let hull = SolidHull { vertices };
                    (extents, SolidExtentsSource::DesignFile, Some(hull))
                }
                None => (None, SolidExtentsSource::Unbounded, None),
            }
        }
    }
}

/// What loading and measuring one design came to.
pub(super) enum Loaded {
    /// The design was measured. `epoch` is the database's invalidation count as read in
    /// the same lock hold as the record.
    Ready {
        /// The figures.
        measured: Measured,
        /// The invalidation epoch the record was read under.
        epoch: u64,
    },
    /// The design's concave tiers could not be resolved (see
    /// [`Measurement::ConcaveUnresolved`]); nothing is saved.
    ConcaveUnresolved,
    /// The design no longer exists.
    Gone,
    /// The record could not be read.
    Failed,
}

/// Loads `entry_id` (holding the database lock only for the read, which also reads the
/// invalidation epoch) and measures it.
fn measure_entry(db: &Mutex<Database>, entry_id: i64) -> Loaded {
    let (epoch, full) = {
        let guard = db.lock().unwrap_or_else(PoisonError::into_inner);
        (
            guard.solid_extents_epoch(),
            guard.get_diagram_full(entry_id),
        )
    };
    match full {
        Ok(Some(full)) => match measure_record(&full) {
            Measurement::Done(measured) => Loaded::Ready { measured, epoch },
            Measurement::ConcaveUnresolved(reason) => {
                warn!(
                    "Rough planner: design #{entry_id} skipped, its concave tiers do not \
                     resolve: {reason}"
                );
                Loaded::ConcaveUnresolved
            }
        },
        Ok(None) => {
            debug!("Rough planner: design #{entry_id} no longer exists");
            Loaded::Gone
        }
        Err(e) => {
            warn!("Rough planner: could not load design #{entry_id}: {e}");
            Loaded::Failed
        }
    }
}

/// How saving one measurement ended.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Saved {
    /// The figures are in the database.
    Stored,
    /// The design's geometry was replaced since it was read, so the figures were dropped.
    Stale,
    /// The write failed.
    Failed,
}

/// Saves one measurement if the design is unchanged since `epoch` was read: the extents
/// and the hull in one transaction (a design measured without a hull drops any older hull
/// row). The database lock is held for the save only.
fn save_measurement(
    db: &Mutex<Database>,
    entry_id: i64,
    epoch: u64,
    (extents, source, hull): &Measured,
) -> Saved {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(0, |d| d.as_secs() as i64);

    let guard = db.lock().unwrap_or_else(PoisonError::into_inner);
    match guard.save_solid_extents_and_hull_if_current(
        entry_id,
        epoch,
        *extents,
        *source,
        hull.as_ref(),
        now,
    ) {
        Ok(true) => Saved::Stored,
        Ok(false) => {
            debug!("Rough planner: design #{entry_id} changed while it was measured; not saved");
            Saved::Stale
        }
        Err(e) => {
            warn!("Rough planner: could not save the measurement of design #{entry_id}: {e}");
            Saved::Failed
        }
    }
}

/// Lays the measurements whose save failed over what the database read back, so this run
/// plans with them although the cache could not keep them. A measurement without a hull
/// also removes the hull read back for it.
pub(super) fn merge_measured(
    stored: &mut BTreeMap<i64, StoredSolidExtents>,
    hulls: &mut BTreeMap<i64, SolidHull>,
    measured: BTreeMap<i64, Measured>,
) {
    for (entry_id, (extents, source, hull)) in measured {
        stored.insert(entry_id, StoredSolidExtents { extents, source });
        match hull {
            Some(hull) => {
                hulls.insert(entry_id, hull);
            }
            None => {
                hulls.remove(&entry_id);
            }
        }
    }
}

/// Which of `ids` (sorted) still need measuring, and whether that scan is only for the
/// convex outlines.
///
/// An id needs a scan when it has no extents row, or when it is a design-file row with
/// usable extents but no cached hull. Unbounded and angle-table rows never get a hull,
/// so a missing hull there is not a reason to measure again. The scan is "outlines
/// only" when every id to measure already has its extents (the first run after the
/// hull cache was introduced).
pub(super) fn ids_needing_scan(
    ids: &[i64],
    extents: &BTreeMap<i64, StoredSolidExtents>,
    hulls: &BTreeMap<i64, SolidHull>,
) -> (Vec<i64>, bool) {
    let mut missing = Vec::new();
    let mut every_id_has_extents = true;
    for &id in ids {
        match extents.get(&id) {
            None => {
                missing.push(id);
                every_id_has_extents = false;
            }
            Some(row) => {
                let wants_hull = row.source == SolidExtentsSource::DesignFile
                    && row.extents.is_some()
                    && !hulls.contains_key(&id);
                if wants_hull {
                    missing.push(id);
                }
            }
        }
    }
    let outlines_only = every_id_has_extents && !missing.is_empty();
    (missing, outlines_only)
}

/// What a scan left behind.
#[derive(Default)]
pub(super) struct ScanOutcome {
    /// Whether the user cancelled (what was measured so far stays saved).
    pub cancelled: bool,
    /// The measurements that could not be saved, by entry id: the run plans with them,
    /// but the next run measures those designs again.
    pub measured: BTreeMap<i64, Measured>,
    /// How many measurements could not be saved although the design was unchanged.
    pub save_failures: usize,
    /// How many designs could not be read from the database.
    pub load_failures: usize,
    /// How many designs panicked while being measured.
    pub panics: usize,
    /// How many designs were skipped because their concave tiers could not be resolved.
    pub concave_unresolved: usize,
}

/// Loads and measures one design (see [`measure_entry`]); a parameter of the scan so a
/// test can stand in for the catalogue's geometry.
type MeasureFn<'a> = &'a (dyn Fn(&Mutex<Database>, i64) -> Loaded + Sync);

/// What the scan lanes share by reference.
struct ScanShared<'a> {
    db: &'a Mutex<Database>,
    reporter: &'a Reporter,
    missing: &'a [i64],
    outlines_only: bool,
    measure: MeasureFn<'a>,
    next: AtomicUsize,
    done: AtomicUsize,
    outcome: Mutex<ScanOutcome>,
}

impl ScanShared<'_> {
    /// Applies `update` to the outcome collected so far.
    fn record(&self, update: impl FnOnce(&mut ScanOutcome)) {
        update(&mut self.outcome.lock().unwrap_or_else(PoisonError::into_inner));
    }

    /// Stores one measurement; a failed write keeps it for this run.
    fn store(&self, entry_id: i64, epoch: u64, measured: Measured) {
        if save_measurement(self.db, entry_id, epoch, &measured) == Saved::Failed {
            self.record(|outcome| {
                outcome.save_failures += 1;
                outcome.measured.insert(entry_id, measured);
            });
        }
    }
}

/// One lane: claims the next unmeasured design until none is left or the user cancels.
fn scan_lane(shared: &ScanShared<'_>) {
    stages::lower_thread_priority();
    let total = shared.missing.len();
    loop {
        if shared.reporter.cancelled() {
            break;
        }
        let index = shared.next.fetch_add(1, Ordering::Relaxed);
        let Some(&entry_id) = shared.missing.get(index) else {
            break;
        };
        let loaded = catch_unwind(AssertUnwindSafe(|| (shared.measure)(shared.db, entry_id)));
        match loaded {
            Ok(Loaded::Ready { measured, epoch }) => shared.store(entry_id, epoch, measured),
            Ok(Loaded::ConcaveUnresolved) => {
                shared.record(|outcome| outcome.concave_unresolved += 1);
            }
            Ok(Loaded::Gone) => {}
            Ok(Loaded::Failed) => shared.record(|outcome| outcome.load_failures += 1),
            Err(payload) => {
                warn!(
                    "Rough planner: measuring design #{entry_id} panicked ({}); skipped",
                    panic_message(&*payload)
                );
                shared.record(|outcome| outcome.panics += 1);
            }
        }
        let finished = shared.done.fetch_add(1, Ordering::Relaxed) + 1;
        let fraction = SCAN_BAND * (finished as f32 / total.max(1) as f32);
        let label = if shared.outlines_only {
            format!(
                "Measuring design outlines {} / {} (one-time)",
                group_thousands(finished),
                group_thousands(total)
            )
        } else {
            format!(
                "Measuring designs {} / {}",
                group_thousands(finished),
                group_thousands(total)
            )
        };
        shared.reporter.report(&label, fraction, finished == total);
    }
}

/// Measures and saves every design in `missing` on `local_lane_count()` scoped threads.
/// What was measured before a cancel stays saved.
pub(super) fn scan_missing(
    db: &Mutex<Database>,
    reporter: &Reporter,
    missing: &[i64],
    outlines_only: bool,
) -> ScanOutcome {
    scan_with(
        db,
        reporter,
        missing,
        outlines_only,
        local_lane_count(),
        &measure_entry,
    )
}

/// [`scan_missing`] on `lanes` threads, with `measure` loading and measuring each design.
fn scan_with(
    db: &Mutex<Database>,
    reporter: &Reporter,
    missing: &[i64],
    outlines_only: bool,
    lanes: usize,
    measure: MeasureFn<'_>,
) -> ScanOutcome {
    if missing.is_empty() {
        return ScanOutcome::default();
    }
    let shared = ScanShared {
        db,
        reporter,
        missing,
        outlines_only,
        measure,
        next: AtomicUsize::new(0),
        done: AtomicUsize::new(0),
        outcome: Mutex::new(ScanOutcome::default()),
    };
    let initial_label = if outlines_only {
        format!(
            "Measuring design outlines 0 / {} (one-time)",
            group_thousands(missing.len())
        )
    } else {
        format!("Measuring designs 0 / {}", group_thousands(missing.len()))
    };
    reporter.report(&initial_label, 0.0, true);

    let lanes = lanes.min(missing.len()).max(1);
    std::thread::scope(|scope| {
        for lane in 0..lanes {
            std::thread::Builder::new()
                .name(format!("rough-plan-scan-{lane}"))
                .stack_size(WORKER_STACK_BYTES)
                .spawn_scoped(scope, || scan_lane(&shared))
                .expect("the operating system could not start a measuring thread");
        }
    });
    let mut outcome = shared
        .outcome
        .into_inner()
        .unwrap_or_else(PoisonError::into_inner);
    outcome.cancelled = reporter.cancelled();
    if outcome.load_failures > 0
        || outcome.panics > 0
        || outcome.save_failures > 0
        || outcome.concave_unresolved > 0
    {
        warn!(
            "Rough planner: of {} designs, {} could not be read, {} panicked while measured, {} \
             had concave tiers that could not be resolved and {} measurements could not be saved",
            missing.len(),
            outcome.load_failures,
            outcome.panics,
            outcome.concave_unresolved,
            outcome.save_failures
        );
    }
    outcome
}

/// The cached extents and hulls of some designs, by entry id.
type Cached = (BTreeMap<i64, StoredSolidExtents>, BTreeMap<i64, SolidHull>);

/// Reads cached extents and hulls for `ids` from the database.
pub(super) fn load_extents_and_hulls(db: &Mutex<Database>, ids: &[i64]) -> Result<Cached, String> {
    let (extents, hulls) = {
        let guard = db.lock().unwrap_or_else(PoisonError::into_inner);
        (guard.solid_extents_for(ids), guard.solid_hulls_for(ids))
    };
    let extents = extents.map_err(|e| format!("Could not read cached extents: {e}"))?;
    let hulls = hulls.map_err(|e| format!("Could not read cached hulls: {e}"))?;
    Ok((extents, hulls))
}

#[cfg(test)]
mod cache_tests;

#[cfg(test)]
mod tests;