draco-oxide 0.1.0-alpha.8

pub mod octahedral_quantization;
pub mod quantization_coordinate_wise;
pub mod to_bits;

use draco_oxide_core::attribute::{Attribute, AttributeType};
use draco_oxide_core::bit_coder::ByteWriter;
use draco_oxide_core::codec::attribute::Portable;
use draco_oxide_core::debug_write;
use draco_oxide_core::types::NdVector;
use draco_oxide_core::types::{ConfigType, Vector};

pub enum Portabilization<Data, const N: usize>
where
    Data: Vector<N> + Portable,
{
    QuantizationCoordinateWise(quantization_coordinate_wise::QuantizationCoordinateWise<Data, N>),
    OctahedralQuantization(octahedral_quantization::OctahedralQuantization<Data, N>),
    ToBits(to_bits::ToBits<Data, N>),
}

impl<Data, const N: usize> Portabilization<Data, N>
where
    Data: Vector<N> + Portable,
    NdVector<N, i32>: Vector<N, Component = i32>,
    NdVector<N, f32>: Vector<N, Component = f32> + Portable,
{
    /// creates a new instance of the portabilization, computes the metadata, and
    /// writes the metadata to the stream.
    // enum_dispatch does not support associated functions, we explicitly write the
    // constructor.
    pub fn new<W>(att: Attribute, cfg: Config, writer: &mut W) -> Self
    where
        W: ByteWriter,
    {
        debug_write!("Start of Portabilization Metadata", writer);
        // cfg.type_.write_to(writer);
        let out = match cfg.type_ {
            PortabilizationType::QuantizationCoordinateWise => {
                Portabilization::QuantizationCoordinateWise(
                    quantization_coordinate_wise::QuantizationCoordinateWise::<_, N>::new(
                        att, cfg, writer,
                    ),
                )
            }
            PortabilizationType::OctahedralQuantization => Portabilization::OctahedralQuantization(
                octahedral_quantization::OctahedralQuantization::new(att, cfg, writer),
            ),
            PortabilizationType::ToBits => {
                Portabilization::ToBits(to_bits::ToBits::new(att, cfg, writer))
            }
            PortabilizationType::Integer => {
                unimplemented!("Integer portabilization is not implemented yet.")
            }
        };
        debug_write!("End of Portabilization Metadata", writer);
        out
    }

    pub fn portabilize(self) -> Attribute {
        match self {
            Portabilization::QuantizationCoordinateWise(qcw) => qcw.portabilize(),
            Portabilization::OctahedralQuantization(oct) => oct.portabilize(),
            Portabilization::ToBits(tb) => tb.portabilize(),
        }
    }
}

pub trait PortabilizationImpl<const N: usize>
where
    NdVector<N, i32>: Vector<N, Component = i32>,
{
    /// portabilizes the whole data.
    fn portabilize(self) -> Attribute;
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PortabilizationType {
    QuantizationCoordinateWise,
    OctahedralQuantization,
    #[allow(dead_code)]
    Integer,
    ToBits,
}

impl PortabilizationType {
    pub(crate) fn get_id(&self) -> u8 {
        match self {
            PortabilizationType::ToBits => 1,
            PortabilizationType::Integer => 1, // Integer is not used in the current implementation, but kept for compatibility.
            PortabilizationType::QuantizationCoordinateWise => 2,
            PortabilizationType::OctahedralQuantization => 3,
        }
    }

    pub(crate) fn write_to<W>(&self, writer: &mut W)
    where
        W: ByteWriter,
    {
        let id = self.get_id();
        writer.write_u8(id);
    }

    pub(crate) fn default_for(ty: AttributeType) -> Self {
        match ty {
            AttributeType::Normal => PortabilizationType::OctahedralQuantization,
            AttributeType::Custom => PortabilizationType::ToBits,
            _ => PortabilizationType::QuantizationCoordinateWise, // default
        }
    }
}

#[derive(Clone, Copy, Debug)]
pub struct Config {
    pub type_: PortabilizationType,
    pub quantization: Quantization,
}

impl ConfigType for Config {
    fn default() -> Self {
        Config {
            type_: PortabilizationType::QuantizationCoordinateWise,
            quantization: Quantization::Bits(11),
        }
    }
}

impl Config {
    pub fn default_for(ty: AttributeType) -> Self {
        match ty {
            AttributeType::Normal => Config {
                type_: PortabilizationType::OctahedralQuantization,
                quantization: Quantization::Bits(8),
            },
            AttributeType::TextureCoordinate => Config {
                type_: PortabilizationType::QuantizationCoordinateWise,
                quantization: Quantization::Bits(10),
            },
            AttributeType::Custom => Config {
                type_: PortabilizationType::ToBits,
                quantization: Quantization::Bits(11), // not used for ToBits
            },
            _ => Self::default(),
        }
    }
}

/// How the quantization resolution (number of bits) for an attribute is
/// determined. All variants ultimately resolve to a bit count in `1..=30`
/// (Draco's cap) via [`Quantization::resolve`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Quantization {
    /// Explicit number of quantization bits.
    Bits(u8),
    /// Derive the bit count from a maximum tolerated quantization error,
    /// measured against the attribute's *observed* value range (the largest
    /// per-axis extent scanned from the data).
    MaxError(f32),
    /// Derive the bit count from a maximum tolerated error against a
    /// *caller-supplied* domain, making the resolution independent of any single
    /// mesh's extent. `range` is the largest per-axis span of the bounding box
    /// (see [`Quantization::from_bounding_box`]).
    Bounded { range: f32, max_error: f32 },
}

impl Default for Quantization {
    fn default() -> Self {
        Quantization::Bits(11)
    }
}

impl Quantization {
    /// Builds a [`Quantization::Bounded`] from an explicit axis-aligned bounding
    /// box; the largest per-axis span sets the resolution.
    pub fn from_bounding_box(min: &[f32], max: &[f32], max_error: f32) -> Self {
        let range = min
            .iter()
            .zip(max.iter())
            .map(|(lo, hi)| hi - lo)
            .fold(0.0_f32, f32::max);
        Quantization::Bounded { range, max_error }
    }

    /// Resolves this spec to a concrete number of quantization bits, clamped to
    /// `1..=30`. `observed_range` is the largest per-axis extent of the data,
    /// used only by [`Quantization::MaxError`]; other variants ignore it.
    pub fn resolve(self, observed_range: f32) -> u8 {
        let bits = match self {
            Quantization::Bits(n) => n,
            Quantization::MaxError(max_error) => bits_for_error(observed_range, max_error),
            Quantization::Bounded { range, max_error } => bits_for_error(range, max_error),
        };
        bits.clamp(1, 30)
    }
}

/// Smallest bit count whose quantization step over `range` does not exceed
/// `max_error`. The decoder dequantizes with step `range / (2^bits - 1)`, so we
/// need `2^bits >= range / max_error + 1`.
fn bits_for_error(range: f32, max_error: f32) -> u8 {
    if range <= 0.0 || max_error <= 0.0 {
        return 1;
    }
    let bits = (range / max_error + 1.0).log2().ceil();
    bits.clamp(1.0, 30.0) as u8
}