axiolid_model/

solid_operation.rs

//! Solid construction relationships and CSG instructions.

use axiolid_core::{BooleanOperator, Point3, Scalar, Transform3, Vec3};

use crate::{NodeId, SectionAtStation, StationFrame, StationedSection};

/// Position of one section along a sectioned sweep.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(deny_unknown_fields)
)]
pub struct Section {
    /// Profile node.
    pub profile: NodeId,
    /// Local placement of the profile.
    pub placement: Transform3,
}

/// Relationship that constructs a solid from lower-level geometry.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(deny_unknown_fields)
)]
pub enum SolidOperation {
    /// Linear extrusion of a profile.
    Extrusion {
        profile: NodeId,
        direction: Vec3,
        depth: Scalar,
    },
    /// Tapered linear extrusion between two profiles.
    TaperedExtrusion {
        start_profile: NodeId,
        end_profile: NodeId,
        direction: Vec3,
        depth: Scalar,
    },
    /// Revolution of a profile.
    Revolution {
        profile: NodeId,
        axis_origin: Point3,
        axis_direction: Vec3,
        angle: Scalar,
    },
    /// Tapered revolution between two profiles.
    TaperedRevolution {
        start_profile: NodeId,
        end_profile: NodeId,
        axis_origin: Point3,
        axis_direction: Vec3,
        angle: Scalar,
    },
    /// Disk swept along a directrix curve.
    ///
    /// `fillet_radius` rounds the corners where consecutive directrix segments
    /// meet, and is meaningful only on a piecewise-linear directrix: a smooth
    /// curve has no corners to round. `None` means sharp corners, which is
    /// also the correct reading for any directrix that is already smooth.
    ///
    /// It is a property of the SWEEP, not of the disk: the disk stays circular
    /// and it is the swept path whose corners are filleted. A consumer that
    /// cannot round corners must refuse a `Some` rather than drop it, because
    /// silently sharpening a pipe run produces geometry that builds, renders,
    /// and is wrong.
    SweptDisk {
        directrix: NodeId,
        radius: Scalar,
        inner_radius: Option<Scalar>,
        parameter_range: Option<(Scalar, Scalar)>,
        /// Corner rounding radius; `None` means sharp corners.
        fillet_radius: Option<Scalar>,
    },
    /// Profile swept along a directrix using a fixed reference direction.
    ///
    /// At each point of the directrix the profile's x axis is the reference
    /// direction projected square to the tangent, its z axis is the tangent
    /// and its y axis is z cross x. The directrix must be tangent
    /// continuous (a corner has no tangent), and the reference must never
    /// be parallel to the tangent, or the profile has no orientation there.
    /// `parameter_range` selects the part of the directrix swept: a curve's
    /// own parameter, and on a composite of curves the arc length.
    ///
    /// The reference compiler proves its chord budget along a chain of
    /// segments and circular arcs, open or closed, when the reference is
    /// normal to the plane of every arc or lies in it, or leans off by a
    /// twist of the frame the walls' half of the budget pays for (up to an
    /// eighth of the budget at the profile's furthest vertex); it sweeps an
    /// arc oblique to the reference beyond that as sampled and reports it
    /// unbounded. It
    /// refuses a corner, a reference parallel to the tangent, a gap between
    /// pieces and a profile that reaches an arc's axis by name. A closed
    /// chain it proves is swept without caps.
    FixedReferenceSweep {
        profile: NodeId,
        directrix: NodeId,
        reference_direction: Vec3,
        parameter_range: Option<(Scalar, Scalar)>,
    },
    /// Profile swept along a directrix constrained by a reference surface.
    SurfaceCurveSweep {
        profile: NodeId,
        directrix: NodeId,
        reference_surface: NodeId,
        parameter_range: Option<(Scalar, Scalar)>,
    },
    /// Sections interpolated along a spine.
    SectionedSpine {
        spine: NodeId,
        sections: Vec<Section>,
    },
    /// General CSG binary operation.
    Boolean {
        left: NodeId,
        right: NodeId,
        operator: BooleanOperator,
    },
    /// Unbounded half-space clipped by a finite boundary geometry.
    BoundedHalfSpace {
        half_space: NodeId,
        /// The boundary in `placement`'s XY plane: a closed 2D curve, or a
        /// `Profile` node whose region it is (#277). A 3D curve, or any
        /// other node, is refused when the graph is built.
        ///
        /// A profile is how a boundary of line and circular-arc segments
        /// is stated: a [`Profile::Contour`](axiolid_profile::Profile)
        /// keeps each arc an exact `Circle2` span, which a polyline
        /// cannot. The half-space is then its side of the plane within the
        /// infinite prism of that region, swept along the plane normal, so
        /// an arc segment bounds it by a right circular cylinder. Which
        /// profile families a compiler accepts is the compiler's to say;
        /// it refuses the others by name.
        boundary: NodeId,
        /// The boundary's own frame, independent of the clip plane.
        ///
        /// The boundary profile is authored in this frame, so its rotation
        /// orients the profile itself rather than the finished solid. A
        /// source format may place the boundary independently of the base
        /// surface. The whole frame is read (#322): its `x` projected into
        /// the plane fixes the boundary's rotation about the clip normal, so
        /// a component along the normal is dropped rather than tilting the
        /// profile out of its own plane, while the frame's own shape -- the
        /// lengths of its `x` and `y`, the lean of `y` against `x`, and its
        /// handedness -- is kept: `y` is laid to the side of `normal x x`,
        /// the other side for a left-handed frame. Only a degenerate frame,
        /// whose axes are parallel or zero, is refused.
        placement: Transform3,
    },
    /// Closed profiles standing at stations along a directrix (#241).
    ///
    /// Each profile is placed in the directrix's `frame` at its station
    /// (profile `x` to the lateral axis, `y` to up, normal along the
    /// tangent; see [`crate::station`]). Between two stations the profiles
    /// are matched vertex for vertex, by ring and index, and interpolated
    /// linearly in distance, as are the offsets, so every section must
    /// flatten to the same ring structure. At least two sections, strictly
    /// increasing in distance, are required.
    StationedSpine {
        directrix: NodeId,
        sections: Vec<StationedSection>,
        frame: StationFrame,
    },
    /// Closed profiles standing at stations along a directrix, each
    /// optionally tagged and explicitly oriented (#246): the general form
    /// of [`SolidOperation::StationedSpine`].
    ///
    /// Each profile is placed as in a `StationedSpine`, its plane turned by
    /// the section's orientation, and interpolated linearly in distance
    /// with the next. Untagged sections are matched by ring and index;
    /// tagged ones by tag, every section carrying the same tags (see
    /// [`crate::station`]). At least two sections, strictly increasing in
    /// distance, all tagged or none, are required.
    SectionsAtStations {
        directrix: NodeId,
        sections: Vec<SectionAtStation>,
        frame: StationFrame,
    },
    // Added after every earlier variant, so their implicit discriminants
    // stay as they were (#321).
    /// A half-space bounded by the prism of a boundary along its
    /// placement's `z` (#321): the side of the plane that `half_space`
    /// keeps, within the lines through the boundary's region parallel to
    /// `placement`'s `z`, infinite both ways and at any angle to the plane.
    ///
    /// This is how IFC's `IfcPolygonalBoundedHalfSpace` is bounded, by its
    /// `Position`: a vertical prism under a sloped roof plane, the common
    /// gable clip, which [`SolidOperation::BoundedHalfSpace`] (its prism
    /// always along the plane normal) cannot state. The boundary's point
    /// `(u, v)` lies at `placement * (u, v, 0)`, the frame read as written:
    /// its scale, shear and handedness all shape the prism. Only the
    /// direction of `z` counts, not its length or sign. A `z` within the
    /// angular tolerance of the plane never crosses it, and a placement
    /// whose axes are parallel or zero has no prism: both are refused by
    /// name when compiled.
    BoundedHalfSpaceAlongZ {
        half_space: NodeId,
        /// The boundary in `placement`'s XY plane, as for
        /// [`SolidOperation::BoundedHalfSpace`]: a closed 2D curve, or a
        /// `Profile` node whose region it is. An arc segment bounds the
        /// half-space by the cylinder of lines through it along `z`.
        boundary: NodeId,
        /// The boundary's frame, its `z` the prism's axis.
        placement: Transform3,
    },
}

impl SolidOperation {
    pub(crate) fn references(&self, out: &mut Vec<NodeId>) {
        match self {
            Self::Extrusion { profile, .. } | Self::Revolution { profile, .. } => {
                out.push(*profile)
            }
            Self::TaperedExtrusion {
                start_profile,
                end_profile,
                ..
            }
            | Self::TaperedRevolution {
                start_profile,
                end_profile,
                ..
            } => out.extend([*start_profile, *end_profile]),
            Self::SweptDisk { directrix, .. } => out.push(*directrix),
            Self::FixedReferenceSweep {
                profile, directrix, ..
            } => out.extend([*profile, *directrix]),
            Self::SurfaceCurveSweep {
                profile,
                directrix,
                reference_surface,
                ..
            } => out.extend([*profile, *directrix, *reference_surface]),
            Self::SectionedSpine { spine, sections } => {
                out.push(*spine);
                out.extend(sections.iter().map(|section| section.profile));
            }
            Self::StationedSpine {
                directrix,
                sections,
                ..
            } => {
                out.push(*directrix);
                out.extend(sections.iter().map(|section| section.profile));
            }
            Self::SectionsAtStations {
                directrix,
                sections,
                ..
            } => {
                out.push(*directrix);
                out.extend(sections.iter().map(|section| section.profile));
            }
            Self::Boolean { left, right, .. } => out.extend([*left, *right]),
            Self::BoundedHalfSpace {
                half_space,
                boundary,
                ..
            }
            | Self::BoundedHalfSpaceAlongZ {
                half_space,
                boundary,
                ..
            } => out.extend([*half_space, *boundary]),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::graph::GeometryGraphBuilder;
    use crate::node::GeometryNode;
    use axiolid_core::Vec3;

    fn directrix(builder: &mut GeometryGraphBuilder) -> NodeId {
        builder.push(GeometryNode::Point3(Vec3::ZERO)).unwrap()
    }

    /// A fillet radius does not add a node reference.
    ///
    /// `references` drives graph traversal and validation, so a scalar that
    /// leaked into it would be read as a `NodeId` and either dangle or alias
    /// an unrelated node. The fillet is geometry data, not a reference.
    #[test]
    fn a_fillet_radius_is_not_a_node_reference() {
        let mut builder = GeometryGraphBuilder::default();
        let curve = directrix(&mut builder);

        let sharp = SolidOperation::SweptDisk {
            directrix: curve,
            radius: 0.05,
            inner_radius: None,
            parameter_range: None,
            fillet_radius: None,
        };
        let rounded = SolidOperation::SweptDisk {
            directrix: curve,
            radius: 0.05,
            inner_radius: None,
            parameter_range: None,
            fillet_radius: Some(0.09),
        };

        let mut sharp_refs = Vec::new();
        sharp.references(&mut sharp_refs);
        let mut rounded_refs = Vec::new();
        rounded.references(&mut rounded_refs);

        assert_eq!(sharp_refs, vec![curve]);
        assert_eq!(
            sharp_refs, rounded_refs,
            "a fillet changes geometry, not the reference graph"
        );
    }

    /// Sharp and rounded sweeps are distinguishable.
    ///
    /// This is the whole reason the field exists. If they compared equal, a
    /// consumer could not tell a filleted pipe run from a mitred one, and
    /// dropping the fillet would be undetectable downstream.
    #[test]
    fn a_fillet_radius_distinguishes_two_otherwise_identical_sweeps() {
        let mut builder = GeometryGraphBuilder::default();
        let curve = directrix(&mut builder);

        let common = |fillet| SolidOperation::SweptDisk {
            directrix: curve,
            radius: 0.05,
            inner_radius: Some(0.04),
            parameter_range: Some((0.0, 2.0)),
            fillet_radius: fillet,
        };
        assert_ne!(common(None), common(Some(0.09)));
        assert_eq!(common(Some(0.09)), common(Some(0.09)));
    }
}