brep_kernel/edit/direct_edit/

face_offset_torus.rs

use super::*;

/// Push a full toroidal face by changing its tube radius exactly.
///
/// This first torus slice deliberately accepts only an untrimmed torus whose
/// boundary edges are intrinsic periodic seams (both incidences belong to the
/// pushed face). Boolean-trimmed torus rims need neighbour re-intersection and
/// are refused before mutation. The offset carrier preserves the source knot
/// vectors, weights, and `(u,v)` parameterization, so existing pcurves remain
/// valid and the two 3D seam curves can be rematerialized as exact iso-curves.
///
/// An intrinsic boundary that is NOT an iso line is no longer refused:
/// [`crate::image_curve`] builds its 3D image on the offset torus. That lane is
/// unreached by the corpus today — the neighbour-trim gate above rejects every
/// trimmed torus first (refusal census §3.6) — so it is a latent restriction
/// removed, not a measured behaviour change.
pub fn offset_torus_face(
    solid: &BrepSolid,
    face_id: u64,
    distance: f64,
) -> Result<BrepSolid, String> {
    if !distance.is_finite() {
        return Err("offset_torus_face: distance must be finite".into());
    }
    let scale = solid_model_scale(solid);
    let tolerance = (scale * 1e-7).max(1e-9);
    // Bar for the general 3D-image ladder: the kernel's single named
    // fit-accuracy field, not the identity band `tolerance` above.
    let fit_tolerance = crate::KernelTolerances::for_scale(scale, 1e-7).intersection_fit;
    let (shell_index, face_index) =
        find_face(solid, face_id).ok_or_else(|| format!("offset_torus_face: no face {face_id}"))?;
    let face = &solid.shells[shell_index].faces[face_index];
    let Some(AnalyticSurface::Torus {
        frame,
        major_radius,
        minor_radius,
    }) = face.surface.analytic()
    else {
        return Err("offset_torus_face: the pushed face is not a torus".into());
    };

    // Positive push follows the face's outward normal. For a cavity torus the
    // topological normal opposes the tube radial, so positive distance shrinks
    // the carrier instead of growing it.
    let [u0, u1] = face.surface.domain_u()?;
    let [v0, v1] = face.surface.domain_v()?;
    let (um, vm) = (0.5 * (u0 + u1), 0.5 * (v0 + v1));
    let point = face.surface.evaluate(um, vm)?;
    let mut normal = face.surface.normal(um, vm)?;
    if !face.same_sense {
        normal = normal.scale(-1.0);
    }
    let relative = point.sub(frame.origin);
    let axial = relative.dot(frame.axis);
    let radial_direction = relative.sub(frame.axis.scale(axial)).normalized()?;
    let tube_center = frame
        .origin
        .add(frame.axis.scale(axial))
        .add(radial_direction.scale(*major_radius));
    let tube_radial = point.sub(tube_center);
    let outward_sign = if normal.dot(tube_radial) >= 0.0 {
        1.0
    } else {
        -1.0
    };
    let minor_new = *minor_radius + distance * outward_sign;
    if minor_new <= tolerance {
        return Err("offset_torus_face: the push collapses the tube radius — refusing".into());
    }
    if minor_new >= *major_radius - tolerance {
        return Err("offset_torus_face: the push creates a horn/spindle torus — refusing".into());
    }

    // A trimmed rim has another incident face. Keep that harder neighbour-heal
    // slice out of this exact full-torus path.
    let mut faces_of_edge: HashMap<u64, Vec<u64>> = HashMap::default();
    for shell in &solid.shells {
        for candidate in &shell.faces {
            for loop_record in &candidate.loops {
                for coedge in &loop_record.coedges {
                    faces_of_edge
                        .entry(coedge.edge_id)
                        .or_default()
                        .push(candidate.id);
                }
            }
        }
    }
    for loop_record in &face.loops {
        for coedge in &loop_record.coedges {
            let incident = faces_of_edge
                .get(&coedge.edge_id)
                .cloned()
                .unwrap_or_default();
            if incident.iter().any(|candidate| *candidate != face_id) {
                return Err(
                    "offset_torus_face: a neighbour-trimmed torus is deferred; only the \
                            full torus is supported in this slice"
                        .into(),
                );
            }
        }
    }

    // offset_surface uses the shell convention positive=opposite outward, so
    // negate the direct-edit distance. For an analytic torus the Greville fit
    // reproduces the exact rational torus with unchanged parameterization.
    let offset = crate::offset_surface(face, -distance, 0.0)?;
    match offset.analytic() {
        Some(AnalyticSurface::Torus {
            frame: out_frame,
            major_radius: out_major,
            minor_radius: out_minor,
        }) if out_frame.origin.sub(frame.origin).length() <= tolerance
            && out_frame.axis.dot(frame.axis).abs() >= 1.0 - 1e-9
            && (*out_major - *major_radius).abs() <= tolerance
            && (*out_minor - minor_new).abs() <= tolerance => {}
        other => {
            return Err(format!(
                "offset_torus_face: offset carrier was not the expected exact torus: {other:?}"
            ))
        }
    }

    let edge_by_id: HashMap<u64, &EdgeRecord> =
        solid.edges.iter().map(|edge| (edge.id, edge)).collect();
    let mut rebuilt_edges: HashMap<u64, (NurbsCurve, f64, f64)> = HashMap::default();
    let mut rebuilt_vertices: HashMap<u64, Vec3> = HashMap::default();
    for loop_record in &face.loops {
        for coedge in &loop_record.coedges {
            if rebuilt_edges.contains_key(&coedge.edge_id) {
                continue;
            }
            let edge = *edge_by_id
                .get(&coedge.edge_id)
                .ok_or_else(|| format!("offset_torus_face: missing edge {}", coedge.edge_id))?;
            let [q0, q1] = coedge.pcurve.domain()?;
            let a = coedge.pcurve.evaluate(q0)?;
            let b = coedge.pcurve.evaluate(q1)?;
            let m = coedge.pcurve.evaluate(0.5 * (q0 + q1))?;
            let uv_tolerance = 1e-8;
            // The two iso lanes are untouched: a periodic seam is an exact iso
            // of the same-basis offset torus, so every solid this path already
            // builds stays BIT-IDENTICAL.
            let iso = if (a.x - b.x).abs() <= uv_tolerance && (a.x - m.x).abs() <= uv_tolerance {
                Some((offset.iso_curve_u(a.x)?, a.y, b.y))
            } else if (a.y - b.y).abs() <= uv_tolerance && (a.y - m.y).abs() <= uv_tolerance {
                Some((offset.iso_curve_v(a.y)?, a.x, b.x))
            } else {
                None
            };
            // A general intrinsic trim used to be refused here. This path
            // admits only edges with no OTHER incident face, so the boundary is
            // definitional and its image on the offset torus IS the new edge.
            let (base, mut start, mut end) = match iso {
                Some(triple) => triple,
                None => {
                    let image = crate::image_curve(
                        &offset,
                        &coedge.pcurve,
                        fit_tolerance,
                        "offset_torus_face",
                    )?;
                    (image.curve, image.t0, image.t1)
                }
            };
            if !coedge.forward {
                std::mem::swap(&mut start, &mut end);
            }
            let [d0, d1] = base.domain()?;
            let (curve, t0, t1) = if start <= end {
                (base, start, end)
            } else {
                (base.reversed()?, d0 + d1 - start, d0 + d1 - end)
            };
            let start_point = curve.evaluate(t0)?;
            let end_point = curve.evaluate(t1)?;
            for (vertex_id, vertex_point) in [
                (edge.start_vertex_id, start_point),
                (edge.end_vertex_id, end_point),
            ] {
                if let Some(known) = rebuilt_vertices.get(&vertex_id) {
                    if known.sub(vertex_point).length() > tolerance {
                        return Err(format!(
                            "offset_torus_face: periodic seams disagree at vertex {vertex_id}"
                        ));
                    }
                } else {
                    rebuilt_vertices.insert(vertex_id, vertex_point);
                }
            }
            rebuilt_edges.insert(edge.id, (curve, t0, t1));
        }
    }

    let mut result = solid.clone();
    result.shells[shell_index].faces[face_index].surface = offset;
    for edge in &mut result.edges {
        if let Some((curve, t0, t1)) = rebuilt_edges.get(&edge.id) {
            edge.curve = curve.clone();
            edge.t0 = *t0;
            edge.t1 = *t1;
        }
    }
    for vertex in &mut result.vertices {
        if let Some(point) = rebuilt_vertices.get(&vertex.id) {
            vertex.point = *point;
        }
    }
    let issues = result.validate();
    if !issues.is_empty() {
        return Err(format!(
            "offset_torus_face: pushed solid failed validation: {issues:?}"
        ));
    }
    if let (Ok(before), Ok(after)) = (solid_signed_volume(solid), solid_signed_volume(&result)) {
        if before * after <= 0.0 {
            return Err("offset_torus_face: the push inverts the solid — refusing".into());
        }
    }
    Ok(result)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn torus_face(solid: &BrepSolid) -> u64 {
        solid
            .shells
            .iter()
            .flat_map(|shell| &shell.faces)
            .find(|face| matches!(face.surface.analytic(), Some(AnalyticSurface::Torus { .. })))
            .expect("torus face")
            .id
    }

    fn torus_radii(solid: &BrepSolid) -> (f64, f64) {
        solid
            .shells
            .iter()
            .flat_map(|shell| &shell.faces)
            .find_map(|face| match face.surface.analytic() {
                Some(AnalyticSurface::Torus {
                    major_radius,
                    minor_radius,
                    ..
                }) => Some((*major_radius, *minor_radius)),
                _ => None,
            })
            .expect("torus radii")
    }

    #[test]
    fn push_full_torus_changes_minor_radius_exactly() {
        for (distance, expected_minor) in [(0.75_f64, 2.75_f64), (-0.75, 1.25)] {
            let torus = crate::make_torus_brep(Vec3::default(), Vec3::new(0.0, 0.0, 1.0), 6.0, 2.0)
                .unwrap();
            let pushed = offset_torus_face(&torus, torus_face(&torus), distance)
                .unwrap_or_else(|error| panic!("push torus by {distance}: {error}"));
            assert!(pushed.validate().is_empty());
            let (major, minor) = torus_radii(&pushed);
            assert!((major - 6.0).abs() < 1e-8);
            assert!((minor - expected_minor).abs() < 1e-8);
            let expected_volume =
                2.0 * std::f64::consts::PI.powi(2) * major * expected_minor.powi(2);
            let volume = solid_signed_volume(&pushed).unwrap().abs();
            assert!((volume - expected_volume).abs() < 1e-2);
        }
    }

    #[test]
    fn push_full_torus_collapse_and_spindle_refuse() {
        let torus =
            crate::make_torus_brep(Vec3::default(), Vec3::new(0.0, 0.0, 1.0), 6.0, 2.0).unwrap();
        let face = torus_face(&torus);
        let collapse = offset_torus_face(&torus, face, -2.0).expect_err("collapse must refuse");
        assert!(collapse.contains("collapse"));
        let spindle = offset_torus_face(&torus, face, 4.0).expect_err("spindle must refuse");
        assert!(spindle.contains("horn/spindle"));
    }

    #[test]
    fn push_toroidal_cavity_positive_shrinks_void() {
        let block = crate::make_box_brep(Vec3::new(-10.0, -10.0, -5.0), 20.0, 20.0, 10.0).unwrap();
        let tool =
            crate::make_torus_brep(Vec3::default(), Vec3::new(0.0, 0.0, 1.0), 4.0, 1.5).unwrap();
        let cavity = crate::boolean_operation(
            &block,
            &tool,
            crate::BooleanOperation::Subtract,
            &crate::BooleanOptions::default(),
        )
        .unwrap();
        let before = solid_signed_volume(&cavity).unwrap().abs();
        let pushed = offset_torus_face(&cavity, torus_face(&cavity), 0.25)
            .unwrap_or_else(|error| panic!("push torus cavity: {error}"));
        assert!(pushed.validate().is_empty());
        let (_, minor) = torus_radii(&pushed);
        assert!((minor - 1.25).abs() < 1e-8, "cavity minor radius {minor}");
        assert!(solid_signed_volume(&pushed).unwrap().abs() > before);
    }
}