mrc 0.8.0

//! MRC-specific type conversions.
//!
//! This module provides the generic conversion trait [`ConvertFrom`] that
//! powers the unified reader conversion system.
//!
//! Specific conversions:
//! - `i8`/`i16`/`u16`/`u8` → `f32` (for `convert::<f32>()` auto-conversion)
//! - `f16` ↔ `f32` (for `convert::<f32>()` auto-conversion and `write_block_as`)
//! - `u8` → `u16`, `u16` → `u8` (Mode 6 utilities)
//! - Mode 0 reinterpretation (signed vs unsigned `i8`)
//! - 4-bit packed data unpacking/packing

use crate::Voxel;
use crate::mode::M0Interpretation;

/// Reinterpret a `Vec<S>` as `Vec<T>` without copying.
///
/// # Safety
/// The caller must ensure that `S` and `T` are the same type at the
/// monomorphized call site, i.e. `TypeId::of::<S>() == TypeId::of::<T>()`.
/// This function verifies this invariant at runtime.
unsafe fn reinterpret_vec<S: 'static, T: 'static>(v: Vec<S>) -> Vec<T> {
    assert!(
        core::any::TypeId::of::<S>() == core::any::TypeId::of::<T>(),
        "reinterpret_vec called with mismatched types"
    );
    let ptr = v.as_ptr() as *mut T;
    let len = v.len();
    let cap = v.capacity();
    core::mem::forget(v);
    // SAFETY: S and T are the same type (TypeId verified above), so size,
    // alignment, and validity invariants are identical.
    unsafe { Vec::from_raw_parts(ptr, len, cap) }
}

#[cfg(feature = "simd")]
use super::simd;

use super::codec::EndianCodec;
use super::codec::decode_slice;
use super::endian::FileEndian;
use crate::Error;
use crate::mode::{ComplexToRealStrategy, Float32Complex, Int16Complex, Mode};

// ============================================================================
// Generic conversion traits
// ============================================================================

/// Convert from a source voxel type to `Self` (reader side).
///
/// Used by [`convert_block`] to dispatch per-mode conversions at runtime.
/// The source type is determined by the file's on-disk mode; `Self` is the
/// target type requested by the caller.
///
/// Only the following target types are wired up:
/// - **`f32`** — universal target, zero-copy identity when source is Float32
/// - **`f16`** — via f32 hub (SIMD F16C/NEON), requires `f16` feature
/// - **`i16`** — shortcut `i8↔i16`, `u16↔i16`; f32 hub for all other sources
/// - **`u16`** — shortcut `i8↔u16`, `i16↔u16`; f32 hub for all other sources
/// - **`i8`** — shortcut `i16↔i8`, `u16↔i8`; f32 hub for all other sources
///
/// # Identity
/// The blanket `impl<T: Voxel> ConvertFrom<T> for T` handles the case
/// where source and target are the same type (no conversion needed).
pub trait ConvertFrom<Src: Voxel>: Voxel {
    /// Convert a slice of source voxels to `Self`.
    fn convert_from(src: &[Src]) -> Vec<Self>;
}

/// Identity conversion: same source and target, just copy.
impl<T: Voxel> ConvertFrom<T> for T {
    fn convert_from(src: &[T]) -> Vec<T> {
        src.to_vec()
    }
}

// ============================================================================
// ConvertFrom implementations (reader side — any source → target)
// ============================================================================

impl ConvertFrom<i16> for f32 {
    fn convert_from(src: &[i16]) -> Vec<f32> {
        convert_i16_slice_to_f32(src)
    }
}

impl ConvertFrom<i8> for f32 {
    fn convert_from(src: &[i8]) -> Vec<f32> {
        convert_i8_slice_to_f32(src)
    }
}

impl ConvertFrom<u16> for f32 {
    fn convert_from(src: &[u16]) -> Vec<f32> {
        convert_u16_slice_to_f32(src)
    }
}

#[cfg(feature = "f16")]
impl ConvertFrom<crate::f16> for f32 {
    fn convert_from(src: &[crate::f16]) -> Vec<f32> {
        convert_f16_slice_to_f32(src)
    }
}

/// Reverse conversion: f32 → f16 for the reader-side convert API.
///
/// Enables `reader.convert::<f16>()` for any source mode (reads, converts
/// through f32 intermediate, then narrows to f16).
#[cfg(feature = "f16")]
impl ConvertFrom<f32> for crate::f16 {
    fn convert_from(src: &[f32]) -> Vec<crate::f16> {
        convert_f32_slice_to_f16(src)
    }
}

/// f32 → i16 for the reader-side convert API.
///
/// Enables `reader.convert::<i16>()` for any source mode via the f32 hub.
/// Uses SIMD when available (see [`convert_f32_slice_to_i16`]).
impl ConvertFrom<f32> for i16 {
    fn convert_from(src: &[f32]) -> Vec<i16> {
        convert_f32_slice_to_i16(src)
    }
}

/// f32 → u16 for the reader-side convert API.
///
/// Enables `reader.convert::<u16>()` for any source mode via the f32 hub.
/// Uses SIMD when available (see [`convert_f32_slice_to_u16`]).
impl ConvertFrom<f32> for u16 {
    fn convert_from(src: &[f32]) -> Vec<u16> {
        convert_f32_slice_to_u16(src)
    }
}

/// f32 → i8 for the reader-side convert API.
///
/// Enables `reader.convert::<i8>()` for any source mode via the f32 hub.
/// Uses SIMD when available (see [`convert_f32_slice_to_i8`]).
impl ConvertFrom<f32> for i8 {
    fn convert_from(src: &[f32]) -> Vec<i8> {
        convert_f32_slice_to_i8(src)
    }
}

// === Packed4Bit (Mode 101) — row-by-row unpack/pack ===

/// Unpack 4-bit packed bytes to `u8`, row-by-row.
///
/// Each row has `nx.div_ceil(2)` bytes in the source.  When `nx` is odd, the
/// last byte's high nibble is padding and is ignored.
///
/// `ny` is the total number of rows (i.e. `ny * nz` for a 3D volume).
///
/// # Nibble ordering (SerialEM convention)
/// - Low 4 bits  (bit 0–3) = first pixel  (smaller X coordinate)
/// - High 4 bits (bit 4–7) = second pixel (larger X coordinate)
pub(crate) fn unpack_u4_bytes_to_u8(src: &[u8], nx: usize, ny: usize) -> Vec<u8> {
    let row_bytes = nx.div_ceil(2);
    let mut dst = Vec::with_capacity(nx * ny);
    for y in 0..ny {
        let row_start = y * row_bytes;
        for x in 0..nx {
            let byte = src[row_start + x / 2];
            let nibble = if x % 2 == 0 {
                byte & 0x0F
            } else {
                (byte >> 4) & 0x0F
            };
            dst.push(nibble);
        }
    }
    dst
}

/// Pack `u8` values (0–15) into 4-bit packed bytes, row-by-row.
///
/// Each row produces `nx.div_ceil(2)` bytes.  When `nx` is odd, the
/// padding high nibble is zero-filled.
///
/// `ny` is the total number of rows (i.e. `ny * nz` for a 3D volume).
///
/// Values exceeding 15 are silently masked to 4 bits (`val & 0x0F`).
/// The caller should validate values beforehand (e.g. in `write_u4_block`).
pub(crate) fn pack_u8_to_u4_bytes(src: &[u8], nx: usize, ny: usize) -> Vec<u8> {
    let row_bytes = nx.div_ceil(2);
    let mut dst = vec![0u8; row_bytes * ny];
    for y in 0..ny {
        let row_start = y * row_bytes;
        for x in 0..nx {
            let val = src[y * nx + x] & 0x0F;
            let byte_idx = row_start + x / 2;
            if x % 2 == 0 {
                dst[byte_idx] = val;
            } else {
                dst[byte_idx] |= val << 4;
            }
        }
    }
    dst
}

/// Reinterpret Mode 0 (8-bit) data as signed or unsigned and convert to `f32`.
pub fn reinterpret_m0(data: &[u8], interp: M0Interpretation) -> Vec<f32> {
    match interp {
        M0Interpretation::Signed => {
            // SAFETY: `u8` and `i8` have the same size and alignment; the byte
            // pattern is valid for `i8` because every bit pattern is valid for `i8`.
            let src: &[i8] =
                unsafe { core::slice::from_raw_parts(data.as_ptr() as *const i8, data.len()) };
            convert_i8_slice_to_f32(src)
        }
        M0Interpretation::Unsigned => convert_u8_slice_to_f32(data),
    }
}

// === Batch slice conversions (used by convert::<f32>().slices()) ===

/// Batch conversion from i8 to f32 using SIMD when available.
#[cfg(feature = "simd")]
pub(crate) fn convert_i8_slice_to_f32(src: &[i8]) -> Vec<f32> {
    simd::convert_i8_to_f32_simd(src)
}

/// Batch conversion from i8 to f32 (scalar fallback).
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_i8_slice_to_f32(src: &[i8]) -> Vec<f32> {
    src.iter().map(|&x| x as f32).collect()
}

/// Batch conversion from i16 to f32 using SIMD when available.
#[cfg(feature = "simd")]
pub(crate) fn convert_i16_slice_to_f32(src: &[i16]) -> Vec<f32> {
    simd::convert_i16_to_f32_simd(src)
}

/// Batch conversion from i16 to f32 (scalar fallback).
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_i16_slice_to_f32(src: &[i16]) -> Vec<f32> {
    src.iter().map(|&x| x as f32).collect()
}

/// Batch conversion from u16 to f32 using SIMD when available.
#[cfg(feature = "simd")]
pub(crate) fn convert_u16_slice_to_f32(src: &[u16]) -> Vec<f32> {
    simd::convert_u16_to_f32_simd(src)
}

/// Batch conversion from u16 to f32 (scalar fallback).
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_u16_slice_to_f32(src: &[u16]) -> Vec<f32> {
    src.iter().map(|&x| x as f32).collect()
}

/// Batch conversion from u8 to f32 using SIMD when available.
#[cfg(feature = "simd")]
pub(crate) fn convert_u8_slice_to_f32(src: &[u8]) -> Vec<f32> {
    simd::convert_u8_to_f32_simd(src)
}

/// Batch conversion from u8 to f32 (scalar fallback).
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_u8_slice_to_f32(src: &[u8]) -> Vec<f32> {
    src.iter().map(|&x| x as f32).collect()
}

/// Batch conversion from f16 to f32 using SIMD when available.
#[cfg(all(feature = "simd", feature = "f16"))]
pub(crate) fn convert_f16_slice_to_f32(src: &[crate::f16]) -> Vec<f32> {
    simd::convert_f16_to_f32_simd(src)
}

/// Batch conversion from f16 to f32 (scalar fallback).
#[cfg(all(feature = "f16", not(feature = "simd")))]
pub(crate) fn convert_f16_slice_to_f32(src: &[crate::f16]) -> Vec<f32> {
    src.iter().map(|&v| f32::from(v)).collect()
}

/// Batch conversion from f32 to f16 using SIMD when available.
#[cfg(all(feature = "simd", feature = "f16"))]
pub(crate) fn convert_f32_slice_to_f16(src: &[f32]) -> Vec<crate::f16> {
    simd::convert_f32_to_f16_simd(src)
}

/// Batch conversion from f32 to f16 (scalar fallback).
#[cfg(all(feature = "f16", not(feature = "simd")))]
pub(crate) fn convert_f32_slice_to_f16(src: &[f32]) -> Vec<crate::f16> {
    src.iter().map(|&v| crate::f16::from_f32(v)).collect()
}

// ============================================================================
// Write-side conversions (f32 → integer types)
// ============================================================================

/// Convert `f32` values to `i16`, clamping to the representable range.
#[cfg(feature = "simd")]
pub(crate) fn convert_f32_slice_to_i16(src: &[f32]) -> Vec<i16> {
    simd::convert_f32_to_i16_simd(src)
}

/// Convert `f32` values to `i16`, clamping to the representable range.
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_f32_slice_to_i16(src: &[f32]) -> Vec<i16> {
    src.iter()
        .map(|&v| {
            if v >= i16::MAX as f32 {
                i16::MAX
            } else if v <= i16::MIN as f32 {
                i16::MIN
            } else {
                v as i16
            }
        })
        .collect()
}

/// Convert `f32` values to `u16`, clamping to the representable range.
/// Negative values are clamped to 0.
#[cfg(feature = "simd")]
pub(crate) fn convert_f32_slice_to_u16(src: &[f32]) -> Vec<u16> {
    simd::convert_f32_to_u16_simd(src)
}

/// Convert `f32` values to `u16`, clamping to the representable range.
/// Negative values are clamped to 0.
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_f32_slice_to_u16(src: &[f32]) -> Vec<u16> {
    src.iter()
        .map(|&v| {
            if v >= u16::MAX as f32 {
                u16::MAX
            } else if v <= 0.0 {
                0
            } else {
                v as u16
            }
        })
        .collect()
}

/// Convert `f32` values to `i8`, clamping to the representable range.
#[cfg(feature = "simd")]
pub(crate) fn convert_f32_slice_to_i8(src: &[f32]) -> Vec<i8> {
    simd::convert_f32_to_i8_simd(src)
}

/// Convert `f32` values to `i8`, clamping to the representable range.
#[cfg(not(feature = "simd"))]
pub(crate) fn convert_f32_slice_to_i8(src: &[f32]) -> Vec<i8> {
    src.iter()
        .map(|&v| {
            if v >= i8::MAX as f32 {
                i8::MAX
            } else if v <= i8::MIN as f32 {
                i8::MIN
            } else {
                v as i8
            }
        })
        .collect()
}

// ============================================================================
// Fused f32 → encoded bytes (used by write_block_as_body! macro)
// ============================================================================

/// Convert f32 data to a target voxel type, then encode into bytes.
fn convert_f32_to_bytes<T: crate::Voxel + EndianCodec + Sync>(
    src: &[f32],
    endian: FileEndian,
    convert: fn(&[f32]) -> Vec<T>,
) -> Vec<u8> {
    let values = convert(src);
    let mut buf = vec![0u8; values.len() * T::BYTE_SIZE];
    // SAFETY: buf size matches values length times element size, guaranteed by construction.
    let _ = crate::engine::codec::encode_slice(&values, &mut buf, endian);
    buf
}

/// Convert f32 slice to encoded i16 bytes in the target endianness.
pub(crate) fn convert_f32_to_i16_bytes(src: &[f32], endian: FileEndian) -> Vec<u8> {
    convert_f32_to_bytes::<i16>(src, endian, convert_f32_slice_to_i16)
}

/// Convert f32 slice to encoded u16 bytes in the target endianness.
pub(crate) fn convert_f32_to_u16_bytes(src: &[f32], endian: FileEndian) -> Vec<u8> {
    convert_f32_to_bytes::<u16>(src, endian, convert_f32_slice_to_u16)
}

/// Convert f32 slice to encoded i8 bytes in the target endianness.
pub(crate) fn convert_f32_to_i8_bytes(src: &[f32], endian: FileEndian) -> Vec<u8> {
    convert_f32_to_bytes::<i8>(src, endian, convert_f32_slice_to_i8)
}

/// Convert f32 slice to encoded f16 bytes in the target endianness.
#[cfg(feature = "f16")]
pub(crate) fn convert_f32_to_f16_bytes(src: &[f32], endian: FileEndian) -> Vec<u8> {
    convert_f32_to_bytes::<crate::f16>(src, endian, convert_f32_slice_to_f16)
}

// ============================================================================
// Generic conversion dispatcher — single match over all source modes
// ============================================================================

/// Decode a raw byte block to its native MRC type, dispatching at runtime.
///
/// Returns [`OwnedData`] with the correct typed `Vec` for the file's mode.
/// This is the runtime-dispatched counterpart of [`decode_block`] which
/// requires a compile-time type parameter.
///
/// For native-endian data this is a simple memcpy.  For non-native endian
/// it decodes element-by-element with byte swapping.
pub(crate) fn decode_block_to_any(
    bytes: &[u8],
    mode: Mode,
    endian: FileEndian,
) -> Result<crate::mode::OwnedData, Error> {
    Ok(match mode {
        Mode::Int8 => {
            let src = decode_slice::<i8>(bytes, endian)?;
            crate::mode::OwnedData::Int8(src)
        }
        Mode::Int16 => {
            let src = decode_slice::<i16>(bytes, endian)?;
            crate::mode::OwnedData::Int16(src)
        }
        Mode::Float32 => {
            let src = decode_slice::<f32>(bytes, endian)?;
            crate::mode::OwnedData::Float32(src)
        }
        Mode::Int16Complex => {
            let src = decode_slice::<Int16Complex>(bytes, endian)?;
            crate::mode::OwnedData::Int16Complex(src)
        }
        Mode::Float32Complex => {
            let src = decode_slice::<Float32Complex>(bytes, endian)?;
            crate::mode::OwnedData::Float32Complex(src)
        }
        Mode::Uint16 => {
            let src = decode_slice::<u16>(bytes, endian)?;
            crate::mode::OwnedData::Uint16(src)
        }
        #[cfg(feature = "f16")]
        Mode::Float16 => {
            let src = decode_slice::<crate::f16>(bytes, endian)?;
            crate::mode::OwnedData::Float16(src)
        }
        #[cfg(not(feature = "f16"))]
        Mode::Float16 => return Err(Error::UnsupportedMode),
        Mode::Packed4Bit => {
            // Packed4Bit data is stored as raw bytes; no endian conversion needed.
            crate::mode::OwnedData::Packed4Bit(bytes.to_vec())
        }
    })
}

/// Convert a raw byte slice from any MRC mode to target type `T`.
///
/// This is the single dispatch point for all reader-side conversions.
/// The source mode is determined at runtime (from the file's header);
/// the target type `T` is a compile-time generic.
///
/// # Parameters
/// - `bytes` — raw voxel data bytes for the block
/// - `mode` — the file's on-disk mode
/// - `endian` — detected file endianness
/// - `block_shape` — dimensions `[sx, sy, sz]` of the block.  For Packed4Bit
///   this is used to compute the nibble-unpack row stride (`sx`) and total
///   row count (`sy × sz`).  For other modes it is unused.
///
/// # Dispatch (in order)
/// 1. **Fused integer shortcut** — when source and target are both narrow
///    integers (`i8↔i16`, `i8↔u16`, `i16↔u16`), decodes and converts in a
///    single pass, eliminating the intermediate `Vec<Src>` allocation.
/// 2. **Fused Float32 shortcut** — `Float32→i16` and `Float32→u16` also
///    fuse decode+clamp into one pass.
/// 3. **f32 hub fallback** — every other source mode (Float16, Float32
///    (identity), complex, Packed4Bit) is decoded to `Vec<f32>` first, then
///    converted to `T` via [`ConvertFrom<f32>`]. Complex modes use the given
///    `complex_strategy` (default: [`Magnitude`](ComplexToRealStrategy::Magnitude)).
///    When `T == f32` the intermediate is reused directly (no clone).
///
/// # Parallelism
/// For large multi-plane blocks (≥`PAR_MIN_VOXELS` voxels, `sz > 1`), the
/// block is split by Z and each chunk is processed independently via rayon
/// (requires the `parallel` feature, enabled by default).
#[allow(clippy::too_many_arguments)]
pub(crate) fn convert_block<T>(
    bytes: &[u8],
    mode: Mode,
    endian: FileEndian,
    block_shape: [usize; 3],
    complex_strategy: ComplexToRealStrategy,
    m0_interp: M0Interpretation,
) -> Result<Vec<T>, Error>
where
    T: Voxel + ConvertFrom<f32>,
{
    #[cfg(feature = "parallel")]
    let [sx, sy, sz] = block_shape;

    // Parallel path for large multi-plane blocks (Packed4Bit excluded — its
    // nibble layout makes Z-splitting non-trivial, and it is rarely used with
    // large volumes).
    #[cfg(feature = "parallel")]
    if sz > 1
        && sx * sy > 0
        && sx * sy * sz >= crate::engine::codec::PAR_MIN_VOXELS
        && mode != Mode::Packed4Bit
    {
        use rayon::prelude::*;
        let b = mode.byte_size();
        let plane_bytes = sx * sy * b;
        let planes_per_chunk = (crate::engine::codec::PAR_MIN_VOXELS / (sx * sy)).max(1);

        let specs: Vec<(usize, usize)> = (0..sz)
            .step_by(planes_per_chunk)
            .map(|z_start| {
                let nplanes = planes_per_chunk.min(sz - z_start);
                (z_start, nplanes)
            })
            .collect();

        let results: Vec<Result<Vec<T>, Error>> = specs
            .into_par_iter()
            .map(|(z_start, nplanes)| {
                let byte_off = z_start * plane_bytes;
                let chunk_bytes = &bytes[byte_off..byte_off + nplanes * plane_bytes];
                let chunk_shape = [sx, sy, nplanes];
                convert_block_seq(
                    chunk_bytes,
                    mode,
                    endian,
                    chunk_shape,
                    complex_strategy,
                    m0_interp,
                )
            })
            .collect();

        let mut output = Vec::with_capacity(sx * sy * sz);
        for r in results {
            output.extend(r?);
        }
        return Ok(output);
    }

    convert_block_seq(
        bytes,
        mode,
        endian,
        block_shape,
        complex_strategy,
        m0_interp,
    )
}

/// Sequential implementation of [`convert_block`] (no parallelism).
///
/// Extracted so parallel chunks can call it directly without re-entering the
/// parallel dispatch in [`convert_block`].
#[allow(clippy::too_many_arguments)]
fn convert_block_seq<T>(
    bytes: &[u8],
    mode: Mode,
    endian: FileEndian,
    block_shape: [usize; 3],
    complex_strategy: ComplexToRealStrategy,
    m0_interp: M0Interpretation,
) -> Result<Vec<T>, Error>
where
    T: Voxel + ConvertFrom<f32>,
{
    // Identity path: file mode matches target type — decode directly,
    // skipping the f32 hub entirely.
    if mode == T::MODE {
        return decode_slice::<T>(bytes, endian);
    }

    // Direct integer↔integer shortcuts — avoids the f32 intermediate
    // (which would add 4N bytes of intermediate storage for narrow types).
    // Uses fused decode+convert functions that process raw bytes directly.
    {
        // i16 → i8
        if mode == Mode::Int16 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<i8>() {
            let r = decode_i16_to_i8(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == i8, so sizes match.
            return Ok(unsafe { reinterpret_vec::<i8, T>(r) });
        }
        // i8 → i16
        if mode == Mode::Int8 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<i16>() {
            let r = decode_i8_to_i16(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == i16, so sizes match.
            return Ok(unsafe { reinterpret_vec::<i16, T>(r) });
        }
        // u16 → i8
        if mode == Mode::Uint16 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<i8>() {
            let r = decode_u16_to_i8(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == i8, so sizes match.
            return Ok(unsafe { reinterpret_vec::<i8, T>(r) });
        }
        // i8 → u16
        if mode == Mode::Int8 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<u16>() {
            let r = decode_i8_to_u16(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == u16, so sizes match.
            return Ok(unsafe { reinterpret_vec::<u16, T>(r) });
        }
        // u16 → i16
        if mode == Mode::Uint16 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<i16>() {
            let r = decode_u16_to_i16(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == i16, so sizes match.
            return Ok(unsafe { reinterpret_vec::<i16, T>(r) });
        }
        // i16 → u16
        if mode == Mode::Int16 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<u16>() {
            let r = decode_i16_to_u16(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == u16, so sizes match.
            return Ok(unsafe { reinterpret_vec::<u16, T>(r) });
        }
        // f32 → i16 (fused decode+clamp, eliminates Vec<f32>)
        if mode == Mode::Float32 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<i16>() {
            let r = decode_f32_to_i16(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == i16, so sizes match.
            return Ok(unsafe { reinterpret_vec::<i16, T>(r) });
        }
        // f32 → u16 (fused decode+clamp, eliminates Vec<f32>)
        if mode == Mode::Float32 && core::any::TypeId::of::<T>() == core::any::TypeId::of::<u16>() {
            let r = decode_f32_to_u16(bytes, endian)?;
            // SAFETY: TypeId checked above guarantees T == u16, so sizes match.
            return Ok(unsafe { reinterpret_vec::<u16, T>(r) });
        }
    }

    // Fall back to f32 hub
    //
    // Packed4Bit is handled here (not in convert_block_inner) because the
    // nibble-unpack step needs the block's actual dimensions (sx, sy × sz),
    // not the volume's (nx, ny).  Passing volume dims would miscompute the
    // row stride and row count for sub-block or multi-slice reads.
    let f32_data = match mode {
        Mode::Packed4Bit => {
            let sx = block_shape[0];
            let total_rows = block_shape[1] * block_shape[2];
            let unpacked = unpack_u4_bytes_to_u8(bytes, sx, total_rows);
            convert_u8_slice_to_f32(&unpacked)
        }
        other => convert_block_inner(bytes, other, endian, complex_strategy, m0_interp)?,
    };
    // Avoid the identity-clone when T == f32 by reusing the allocation.
    // SAFETY: The TypeId check guarantees T and f32 are the same type at the
    // monomorphized call site; the compiler optimizes the branch away.
    if core::any::TypeId::of::<T>() == core::any::TypeId::of::<f32>() {
        let ptr = f32_data.as_ptr() as *mut T;
        let len = f32_data.len();
        let cap = f32_data.capacity();
        core::mem::forget(f32_data);
        Ok(unsafe { Vec::from_raw_parts(ptr, len, cap) })
    } else {
        Ok(T::convert_from(&f32_data))
    }
}

/// Fused: decode raw bytes directly to `Vec<f32>` without allocating
/// an intermediate typed Vec for the source mode.
///
/// For native-endian (the common case), source bytes are pointer-cast
/// and passed directly to the SIMD conversion kernel — zero intermediate
/// allocation. For non-native endian, falls back to decode_slice + convert.
fn convert_block_inner(
    bytes: &[u8],
    mode: Mode,
    endian: FileEndian,
    complex_strategy: ComplexToRealStrategy,
    m0_interp: M0Interpretation,
) -> Result<Vec<f32>, Error> {
    match mode {
        Mode::Int8 => match m0_interp {
            M0Interpretation::Signed => {
                let src = decode_slice::<i8>(bytes, endian)?;
                Ok(convert_i8_slice_to_f32(&src))
            }
            M0Interpretation::Unsigned => Ok(reinterpret_m0(bytes, M0Interpretation::Unsigned)),
        },
        Mode::Int16 => {
            if endian.is_native() {
                // SAFETY: `bytes` comes from a `Vec<u8>` (heap, ≥8-byte aligned)
                // or `Mmap` (page-aligned), so it is always 2-byte aligned for `i16`.
                // The byte representation is identical for native endian.
                let src = unsafe {
                    std::slice::from_raw_parts(bytes.as_ptr() as *const i16, bytes.len() / 2)
                };
                Ok(convert_i16_slice_to_f32(src))
            } else {
                let src = decode_slice::<i16>(bytes, endian)?;
                Ok(convert_i16_slice_to_f32(&src))
            }
        }
        Mode::Uint16 => {
            if endian.is_native() {
                // SAFETY: `bytes` is always heap-or-mmap allocated (≥2-byte aligned),
                // and the byte representation is identical for native endian.
                let src = unsafe {
                    std::slice::from_raw_parts(bytes.as_ptr() as *const u16, bytes.len() / 2)
                };
                Ok(convert_u16_slice_to_f32(src))
            } else {
                let src = decode_slice::<u16>(bytes, endian)?;
                Ok(convert_u16_slice_to_f32(&src))
            }
        }
        Mode::Float32 => decode_slice::<f32>(bytes, endian),
        Mode::Float16 => {
            #[cfg(feature = "f16")]
            {
                if endian.is_native() {
                    // SAFETY: `bytes` is always heap-or-mmap allocated (≥2-byte aligned for `f16`).
                    let src = unsafe {
                        std::slice::from_raw_parts(
                            bytes.as_ptr() as *const crate::f16,
                            bytes.len() / 2,
                        )
                    };
                    Ok(convert_f16_slice_to_f32(src))
                } else {
                    let src = decode_slice::<crate::f16>(bytes, endian)?;
                    Ok(convert_f16_slice_to_f32(&src))
                }
            }
            #[cfg(not(feature = "f16"))]
            {
                let _ = endian;
                Err(Error::UnsupportedMode)
            }
        }
        Mode::Float32Complex => {
            let n = bytes.len() / Float32Complex::BYTE_SIZE;
            let mut mag = Vec::with_capacity(n);
            for i in 0..n {
                let c = Float32Complex::from_bytes(bytes, i * Float32Complex::BYTE_SIZE, endian);
                mag.push(c.to_real(complex_strategy));
            }
            Ok(mag)
        }
        Mode::Int16Complex => {
            let n = bytes.len() / Int16Complex::BYTE_SIZE;
            let mut mag = Vec::with_capacity(n);
            for i in 0..n {
                let c = Int16Complex::from_bytes(bytes, i * Int16Complex::BYTE_SIZE, endian);
                mag.push(c.to_real(complex_strategy));
            }
            Ok(mag)
        }
        Mode::Packed4Bit => {
            unreachable!("Packed4Bit is dispatched via convert_block before convert_block_inner")
        }
    }
}

// =============================================================================
// Tests
// =============================================================================

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

    // Test batch conversions
    #[test]
    fn test_convert_i8_slice_to_f32() {
        let input: Vec<i8> = vec![-128, -64, 0, 64, 127];
        let output = convert_i8_slice_to_f32(&input);

        assert_eq!(output.len(), input.len());
        for (src, dst) in input.iter().zip(output.iter()) {
            assert_eq!(*dst, *src as f32);
        }
    }

    #[test]
    fn test_convert_i16_slice_to_f32() {
        let input: Vec<i16> = vec![-32768, -1000, 0, 1000, 32767];
        let output = convert_i16_slice_to_f32(&input);

        assert_eq!(output.len(), input.len());
        for (src, dst) in input.iter().zip(output.iter()) {
            assert_eq!(*dst, *src as f32);
        }
    }

    #[test]
    fn test_convert_u16_slice_to_f32() {
        let input: Vec<u16> = vec![0, 1000, 32767, 65535];
        let output = convert_u16_slice_to_f32(&input);

        assert_eq!(output.len(), input.len());
        for (src, dst) in input.iter().zip(output.iter()) {
            assert_eq!(*dst, *src as f32);
        }
    }

    // Test edge cases
    #[test]
    fn test_convert_empty_slice() {
        let input: Vec<i8> = vec![];
        let output = convert_i8_slice_to_f32(&input);
        assert!(output.is_empty());
    }

    #[test]
    fn test_convert_single_element() {
        let input: Vec<i16> = vec![42];
        let output = convert_i16_slice_to_f32(&input);
        assert_eq!(output.len(), 1);
        assert_eq!(output[0], 42.0f32);
    }

    #[test]
    fn test_convert_large_slice() {
        let input: Vec<i16> = (0..10000).map(|i| (i % 65536) as i16).collect();
        let output = convert_i16_slice_to_f32(&input);

        assert_eq!(output.len(), input.len());
        for (src, dst) in input.iter().zip(output.iter()) {
            assert_eq!(*dst, *src as f32);
        }
    }

    // Test that SIMD and scalar paths produce identical results
    #[test]
    #[cfg(feature = "simd")]
    fn test_simd_scalar_equivalence_i8() {
        let input: Vec<i8> = (-128..=127).collect();
        let simd_result = crate::engine::convert::convert_i8_slice_to_f32(&input);
        let scalar_result: Vec<f32> = input.iter().map(|&x| x as f32).collect();
        assert_eq!(simd_result, scalar_result);
    }

    #[test]
    #[cfg(feature = "simd")]
    fn test_simd_scalar_equivalence_i16() {
        let input: Vec<i16> = (-32768..=-31768).collect(); // Full i16 range would be slow
        let simd_result = crate::engine::convert::convert_i16_slice_to_f32(&input);
        let scalar_result: Vec<f32> = input.iter().map(|&x| x as f32).collect();
        assert_eq!(simd_result, scalar_result);
    }

    #[test]
    #[cfg(feature = "simd")]
    fn test_simd_scalar_equivalence_u16() {
        let input: Vec<u16> = (0..10000).collect();
        let simd_result = crate::engine::convert::convert_u16_slice_to_f32(&input);
        let scalar_result: Vec<f32> = input.iter().map(|&x| x as f32).collect();
        assert_eq!(simd_result, scalar_result);
    }

    // Test M101 unpacking
    #[test]
    fn test_unpack_u4_bytes_to_u8_even() {
        let bytes = vec![0x21, 0x43];
        let result = unpack_u4_bytes_to_u8(&bytes, 4, 1);
        // row: [0x21, 0x43]
        // pixel 0: low of 0x21 = 1
        // pixel 1: high of 0x21 = 2
        // pixel 2: low of 0x43 = 3
        // pixel 3: high of 0x43 = 4
        assert_eq!(result, vec![1, 2, 3, 4]);
    }

    #[test]
    fn test_unpack_u4_bytes_to_u8_odd() {
        // nx=3 → row_bytes = 2; last byte's high nibble is padding
        let bytes = vec![0x21, 0x30]; // low of 0x30 = 0 is the 3rd pixel, high 0x30=3 is padding
        let result = unpack_u4_bytes_to_u8(&bytes, 3, 1);
        // pixel 0: low of 0x21 = 1
        // pixel 1: high of 0x21 = 2
        // pixel 2: low of 0x30 = 0
        assert_eq!(result, vec![1, 2, 0]);
    }

    #[test]
    fn test_pack_u8_to_u4_bytes_even() {
        let values = vec![1, 2, 3, 4];
        let packed = pack_u8_to_u4_bytes(&values, 4, 1);
        assert_eq!(packed, vec![0x21, 0x43]);
    }

    #[test]
    fn test_pack_u8_to_u4_bytes_odd() {
        let values = vec![1, 2, 3];
        let packed = pack_u8_to_u4_bytes(&values, 3, 1);
        // row_bytes = 2; byte0 = 1 | (2 << 4) = 0x21; byte1 = 3 | (0 << 4) = 0x03
        assert_eq!(packed, vec![0x21, 0x03]);
    }

    #[test]
    fn test_pack_unpack_roundtrip() {
        let values: Vec<u8> = vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
        let packed = pack_u8_to_u4_bytes(&values, 8, 2);
        let unpacked = unpack_u4_bytes_to_u8(&packed, 8, 2);
        assert_eq!(unpacked, values);
    }

    #[test]
    fn test_pack_unpack_roundtrip_odd() {
        let values: Vec<u8> = vec![1, 2, 3, 4, 5]; // nx=5, ny=1 → 5 pixels, 3 bytes
        let packed = pack_u8_to_u4_bytes(&values, 5, 1);
        let unpacked = unpack_u4_bytes_to_u8(&packed, 5, 1);
        assert_eq!(unpacked, values);
    }

    // Test M0 reinterpretation
    #[test]
    fn test_reinterpret_m0_signed() {
        let data = vec![0x00, 0x80, 0xFF]; // 0, -128, -1 in signed i8
        let result = reinterpret_m0(&data, M0Interpretation::Signed);
        assert_eq!(result, vec![0.0, -128.0, -1.0]);
    }

    #[test]
    fn test_reinterpret_m0_unsigned() {
        let data = vec![0x00, 0x80, 0xFF]; // 0, 128, 255 in unsigned u8
        let result = reinterpret_m0(&data, M0Interpretation::Unsigned);
        assert_eq!(result, vec![0.0, 128.0, 255.0]);
    }

    // Test ComplexToRealStrategy
    #[test]
    fn test_complex_to_real_strategies() {
        let c = crate::mode::Float32Complex {
            real: 3.0,
            imag: 4.0,
        };
        assert_eq!(c.to_real(ComplexToRealStrategy::RealPart), 3.0);
        assert_eq!(c.to_real(ComplexToRealStrategy::ImaginaryPart), 4.0);
        assert_eq!(c.to_real(ComplexToRealStrategy::Magnitude), 5.0);
        let phase = c.to_real(ComplexToRealStrategy::Phase);
        assert!((phase - 0.927_295_2).abs() < 1e-6);
    }
}

// ============================================================================
// Fused decode+convert functions (eliminate intermediate Vec<Src> allocation)
// ============================================================================

/// Fused: decode bytes as i16, clamp to i8, produce Vec<i8> in one pass.
pub(crate) fn decode_i16_to_i8(bytes: &[u8], endian: FileEndian) -> Result<Vec<i8>, Error> {
    let n = bytes.len() / 2;
    let mut result = vec![0i8; n];
    match endian {
        FileEndian::LittleEndian => {
            for i in 0..n {
                let val = i16::from_le_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.clamp(i8::MIN as i16, i8::MAX as i16) as i8;
            }
        }
        FileEndian::BigEndian => {
            for i in 0..n {
                let val = i16::from_be_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.clamp(i8::MIN as i16, i8::MAX as i16) as i8;
            }
        }
    }
    Ok(result)
}

/// Fused: sign-extend each byte to i16 in one pass (no endian dependency for 1-byte elements).
pub(crate) fn decode_i8_to_i16(bytes: &[u8], _endian: FileEndian) -> Result<Vec<i16>, Error> {
    let n = bytes.len();
    let mut result = Vec::with_capacity(n);
    // i8 has no byte-order concern, just sign-extend
    for &b in bytes {
        result.push(b as i8 as i16);
    }
    Ok(result)
}

/// Fused: decode bytes as u16, clamp to i8, produce Vec<i8> in one pass.
pub(crate) fn decode_u16_to_i8(bytes: &[u8], endian: FileEndian) -> Result<Vec<i8>, Error> {
    let n = bytes.len() / 2;
    let mut result = vec![0i8; n];
    match endian {
        FileEndian::LittleEndian => {
            for i in 0..n {
                let val = u16::from_le_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.min(i8::MAX as u16) as i8;
            }
        }
        FileEndian::BigEndian => {
            for i in 0..n {
                let val = u16::from_be_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.min(i8::MAX as u16) as i8;
            }
        }
    }
    Ok(result)
}

/// Fused: widen each byte to u16 in one pass (negative → 0).
pub(crate) fn decode_i8_to_u16(bytes: &[u8], _endian: FileEndian) -> Result<Vec<u16>, Error> {
    let n = bytes.len();
    let mut result = Vec::with_capacity(n);
    for &b in bytes {
        result.push((b as i8).max(0) as u16);
    }
    Ok(result)
}

/// Fused: decode bytes as u16, produce Vec<i16> in one pass (clamping at i16::MAX).
pub(crate) fn decode_u16_to_i16(bytes: &[u8], endian: FileEndian) -> Result<Vec<i16>, Error> {
    let n = bytes.len() / 2;
    let mut result = vec![0i16; n];
    match endian {
        FileEndian::LittleEndian => {
            for i in 0..n {
                let val = u16::from_le_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.min(i16::MAX as u16) as i16;
            }
        }
        FileEndian::BigEndian => {
            for i in 0..n {
                let val = u16::from_be_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.min(i16::MAX as u16) as i16;
            }
        }
    }
    Ok(result)
}

/// Fused: decode bytes as i16, produce Vec<u16> in one pass (negative → 0).
pub(crate) fn decode_i16_to_u16(bytes: &[u8], endian: FileEndian) -> Result<Vec<u16>, Error> {
    let n = bytes.len() / 2;
    let mut result = vec![0u16; n];
    match endian {
        FileEndian::LittleEndian => {
            for i in 0..n {
                let val = i16::from_le_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.max(0) as u16;
            }
        }
        FileEndian::BigEndian => {
            for i in 0..n {
                let val = i16::from_be_bytes([bytes[i * 2], bytes[i * 2 + 1]]);
                result[i] = val.max(0) as u16;
            }
        }
    }
    Ok(result)
}

/// Fused: decode bytes as f32, clamp to i16, produce Vec<i16> in one pass.
///
/// For native endian, uses SIMD-accelerated clamping (when the `simd` feature
/// is enabled) on a pointer-cast f32 slice — zero allocation for the source.
/// For non-native endian, falls back to decode + SIMD clamp (same as the
/// two-step path; no regression).
pub(crate) fn decode_f32_to_i16(bytes: &[u8], endian: FileEndian) -> Result<Vec<i16>, Error> {
    if endian.is_native() {
        let n = bytes.len() / 4;
        // SAFETY: f32 alignment >= u8 alignment, the byte count is a multiple of 4,
        // and any bit pattern is valid for f32.
        let src = unsafe { core::slice::from_raw_parts(bytes.as_ptr() as *const f32, n) };
        Ok(convert_f32_slice_to_i16(src))
    } else {
        let src = decode_slice::<f32>(bytes, endian)?;
        Ok(convert_f32_slice_to_i16(&src))
    }
}

/// Fused: decode bytes as f32, clamp to u16, produce Vec<u16> in one pass.
///
/// For native endian, uses SIMD-accelerated clamping on a pointer-cast f32 slice.
/// For non-native endian, falls back to decode + SIMD clamp.
pub(crate) fn decode_f32_to_u16(bytes: &[u8], endian: FileEndian) -> Result<Vec<u16>, Error> {
    if endian.is_native() {
        let n = bytes.len() / 4;
        // SAFETY: same reasoning as decode_f32_to_i16 above.
        let src = unsafe { core::slice::from_raw_parts(bytes.as_ptr() as *const f32, n) };
        Ok(convert_f32_slice_to_u16(src))
    } else {
        let src = decode_slice::<f32>(bytes, endian)?;
        Ok(convert_f32_slice_to_u16(&src))
    }
}

// ============================================================================
// u16 → u8 fused decode (fuses endian handling with narrowing)
// ============================================================================

/// Decode raw u16 bytes directly to `Vec<u8>`, fusing endian handling with
/// narrowing validation in a single pass.
///
/// This avoids the intermediate `Vec<u16>` allocation that
/// `decode_slice::<u16>` + `convert_u16_slice_to_u8` would require.
///
/// # Errors
/// Returns [`Error::ValueOutOfRange`] if any u16 value exceeds 255.
pub(crate) fn decode_u16_to_u8(bytes: &[u8], endian: FileEndian) -> Result<Vec<u8>, Error> {
    let n = bytes.len() / 2;
    let mut out = Vec::with_capacity(n);
    match endian {
        FileEndian::LittleEndian => {
            // Little-endian: u16 word = [lo, hi]; for values ≤ 255, hi byte = 0.
            for chunk in bytes.chunks_exact(2) {
                if chunk[1] != 0 {
                    return Err(crate::Error::ValueOutOfRange {
                        value: u16::from_le_bytes([chunk[0], chunk[1]]) as u64,
                        max: 255,
                    });
                }
                out.push(chunk[0]);
            }
        }
        FileEndian::BigEndian => {
            // Big-endian: u16 word = [hi, lo]; for values ≤ 255, hi byte = 0.
            for chunk in bytes.chunks_exact(2) {
                if chunk[0] != 0 {
                    return Err(crate::Error::ValueOutOfRange {
                        value: u16::from_be_bytes([chunk[0], chunk[1]]) as u64,
                        max: 255,
                    });
                }
                out.push(chunk[1]);
            }
        }
    }
    Ok(out)
}

// ============================================================================
// u8 → u16 widening (Mode 6 convenience)
// ============================================================================

/// Widen a `u8` slice to `u16` for writing as Mode 6 (Uint16).
///
/// This matches Python `mrcfile`'s behaviour when given `np.uint8` data:
/// the data is automatically widened to `uint16` (mode 6) because MRC-2014
/// does not define a native unsigned 8-bit mode.
pub fn convert_u8_slice_to_u16(src: &[u8]) -> Vec<u16> {
    src.iter().map(|&v| v as u16).collect()
}

/// Fused: widen u8→u16 and produce encoded bytes, skipping `Vec<u16>`.
/// Saves one allocation per `write_u8_block` call.
pub(crate) fn convert_u8_to_u16_bytes(src: &[u8], endian: FileEndian) -> Vec<u8> {
    let n = src.len();
    let mut buf = vec![0u8; n * 2];
    if endian.is_native() {
        for (i, &v) in src.iter().enumerate() {
            buf[i * 2] = v;
            buf[i * 2 + 1] = 0;
        }
    } else {
        for (i, &v) in src.iter().enumerate() {
            buf[i * 2] = 0;
            buf[i * 2 + 1] = v;
        }
    }
    buf
}

/// Narrow a `u16` slice to `u8`, returning `Err` if any value exceeds 255.
///
/// This is the reverse of [`convert_u8_slice_to_u16`] and is used when
/// reading a Mode 6 file that was originally created from `u8` data.
///
/// # Errors
/// Returns [`Error::ValueOutOfRange`](crate::Error::ValueOutOfRange) if any value exceeds 255.
pub fn convert_u16_slice_to_u8(src: &[u16]) -> Result<Vec<u8>, crate::Error> {
    let mut out = Vec::with_capacity(src.len());
    for &v in src {
        if v > 255 {
            return Err(crate::Error::ValueOutOfRange {
                value: v as u64,
                max: 255,
            });
        }
        out.push(v as u8);
    }
    Ok(out)
}

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

    #[test]
    fn test_convert_u8_to_u16() {
        let src: Vec<u8> = vec![0, 1, 127, 128, 255];
        let dst = convert_u8_slice_to_u16(&src);
        assert_eq!(dst, vec![0u16, 1, 127, 128, 255]);
    }

    #[test]
    fn test_convert_u16_to_u8_ok() {
        let src: Vec<u16> = vec![0, 1, 127, 128, 255];
        let dst = convert_u16_slice_to_u8(&src).unwrap();
        assert_eq!(dst, vec![0u8, 1, 127, 128, 255]);
    }

    #[test]
    fn test_convert_u16_to_u8_overflow() {
        let src: Vec<u16> = vec![0, 256];
        assert!(convert_u16_slice_to_u8(&src).is_err());
    }

    #[test]
    fn test_u8_roundtrip() {
        let original: Vec<u8> = (0..=255).collect();
        let widened = convert_u8_slice_to_u16(&original);
        let narrowed = convert_u16_slice_to_u8(&widened).unwrap();
        assert_eq!(original, narrowed);
    }
}