lumen_geometry/colon/

config.rs

//! Configuration for colon geometry generation.

use super::ColonSegment;

/// Configuration parameters for generating a colon curve.
///
/// All parameters have sensible defaults based on adult human anatomy.
/// Use `seed` to generate procedural variations while maintaining
/// anatomical plausibility.
///
/// # Example
///
/// ```rust
/// use lumen_geometry::colon::ColonConfig;
///
/// // Default adult anatomy
/// let config = ColonConfig::default();
///
/// // Procedurally varied anatomy
/// let varied = ColonConfig {
///     seed: Some(12345),
///     ..Default::default()
/// };
///
/// // Custom configuration
/// let custom = ColonConfig {
///     total_length: 120.0,  // Shorter colon
///     base_radius: 2.5,     // Narrower lumen
///     ..Default::default()
/// };
/// ```
#[derive(Debug, Clone)]
pub struct ColonConfig {
    /// Seed for procedural variation. `None` uses default geometry.
    ///
    /// When set, the seed affects:
    /// - Segment length ratios (within anatomical bounds)
    /// - Flexure angles (within anatomical bounds)
    /// - Radius variations along the length
    /// - Secondary curve wobble
    pub seed: Option<u64>,

    /// Total arc length of the colon in world units.
    ///
    /// Adult human colon is approximately 150cm. Default is scaled
    /// for typical game/simulation use.
    pub total_length: f32,

    /// Base lumen radius in world units.
    ///
    /// This is the default radius; actual radius varies by segment.
    pub base_radius: f32,

    /// Per-segment configuration overrides.
    ///
    /// If `None`, uses default parameters for each segment.
    pub segment_params: Option<[SegmentParams; 8]>,

    /// How much the seed can vary segment lengths.
    ///
    /// Value of 0.0 = no variation, 1.0 = maximum variation.
    /// Default is 0.3 (30% variation from base lengths).
    pub length_variation: f32,

    /// How much the seed can vary flexure angles.
    ///
    /// Value of 0.0 = no variation, 1.0 = maximum variation.
    /// Default is 0.2 (20% variation from base angles).
    pub angle_variation: f32,

    /// Secondary wobble amplitude for organic feel.
    ///
    /// Adds small-scale variation to the centerline path.
    /// Default is 0.1 (10% of radius).
    pub wobble_amplitude: f32,

    /// Frequency of secondary wobble.
    ///
    /// Higher values = more frequent small bends.
    /// Default is 8.0 (approximately 8 wobbles per segment).
    pub wobble_frequency: f32,
}

/// Parameters for a single colon segment.
#[derive(Debug, Clone, Copy)]
pub struct SegmentParams {
    /// Fraction of total length this segment occupies.
    ///
    /// All segment fractions should sum to 1.0.
    pub length_fraction: f32,

    /// Radius multiplier relative to base_radius.
    ///
    /// 1.0 = base radius, 1.2 = 20% wider, etc.
    pub radius_scale: f32,

    /// Curvature intensity for this segment.
    ///
    /// 0.0 = straight, 1.0 = normal curve, 2.0 = sharp bend.
    /// Flexures typically have higher values.
    pub curvature: f32,

    /// Primary bend direction (radians).
    ///
    /// Determines which way this segment curves.
    pub bend_direction: f32,
}

impl Default for ColonConfig {
    fn default() -> Self {
        Self {
            seed: None,
            total_length: 150.0,
            base_radius: 3.0,
            segment_params: None,
            length_variation: 0.3,
            angle_variation: 0.2,
            wobble_amplitude: 0.1,
            wobble_frequency: 8.0,
        }
    }
}

impl ColonConfig {
    /// Create a new config with a specific seed.
    pub fn with_seed(seed: u64) -> Self {
        Self {
            seed: Some(seed),
            ..Default::default()
        }
    }

    /// Get parameters for a specific segment.
    ///
    /// Returns custom params if set, otherwise default for that segment.
    pub fn params_for(&self, segment: ColonSegment) -> SegmentParams {
        if let Some(ref params) = self.segment_params {
            params[segment.index()]
        } else {
            SegmentParams::default_for(segment)
        }
    }
}

impl SegmentParams {
    /// Default parameters for each colon segment.
    ///
    /// Based on anatomical characteristics:
    /// - Flexures are short but sharply curved
    /// - Transverse is longest
    /// - Cecum is widest
    pub fn default_for(segment: ColonSegment) -> Self {
        use std::f32::consts::PI;

        match segment {
            ColonSegment::Rectum => Self {
                length_fraction: 0.08,
                radius_scale: 1.0,
                curvature: 0.2,
                bend_direction: 0.0,
            },
            ColonSegment::Sigmoid => Self {
                length_fraction: 0.12,
                radius_scale: 0.9,
                curvature: 1.5,
                bend_direction: PI * 0.25, // S-curve
            },
            ColonSegment::Descending => Self {
                length_fraction: 0.15,
                radius_scale: 1.0,
                curvature: 0.3,
                bend_direction: PI * 0.5, // Leftward/upward
            },
            ColonSegment::SplenicFlexure => Self {
                length_fraction: 0.05,
                radius_scale: 0.95,
                curvature: 2.5, // Sharp bend
                bend_direction: PI,
            },
            ColonSegment::Transverse => Self {
                length_fraction: 0.25,
                radius_scale: 1.1,
                curvature: 0.4,
                bend_direction: PI * 1.5, // Rightward
            },
            ColonSegment::HepaticFlexure => Self {
                length_fraction: 0.05,
                radius_scale: 0.95,
                curvature: 2.5, // Sharp bend
                bend_direction: 0.0,
            },
            ColonSegment::Ascending => Self {
                length_fraction: 0.20,
                radius_scale: 1.05,
                curvature: 0.3,
                bend_direction: PI * 0.5, // Downward
            },
            ColonSegment::Cecum => Self {
                length_fraction: 0.10,
                radius_scale: 1.3, // Widest section
                curvature: 0.5,
                bend_direction: PI * 0.75,
            },
        }
    }
}

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

    #[test]
    fn default_length_fractions_sum_to_one() {
        let sum: f32 = ColonSegment::ALL
            .iter()
            .map(|s| SegmentParams::default_for(*s).length_fraction)
            .sum();
        assert!(
            (sum - 1.0).abs() < 0.001,
            "Length fractions sum to {}, expected 1.0",
            sum
        );
    }

    #[test]
    fn flexures_have_high_curvature() {
        let splenic = SegmentParams::default_for(ColonSegment::SplenicFlexure);
        let hepatic = SegmentParams::default_for(ColonSegment::HepaticFlexure);
        let transverse = SegmentParams::default_for(ColonSegment::Transverse);

        assert!(splenic.curvature > transverse.curvature);
        assert!(hepatic.curvature > transverse.curvature);
    }

    #[test]
    fn cecum_is_widest() {
        let cecum = SegmentParams::default_for(ColonSegment::Cecum);
        for segment in ColonSegment::ALL.iter() {
            let params = SegmentParams::default_for(*segment);
            assert!(
                cecum.radius_scale >= params.radius_scale,
                "{:?} is wider than Cecum",
                segment
            );
        }
    }
}