moon-nrrd

    Pure MoonBit NRRD read-write library: NRRD0005 header parse, data decode, and symmetric serialization (8 numeric types, raw LE/BE + ASCII, attached/detached)

    nrrd
    nhdr
    scientific
    imaging
    voxel
    grid
    teem
    parse
    encode
    Download zip
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    6 days ago
    Downloads
    15

    #moon-nrrd

    Pure MoonBit NRRD read-write library. Parses NRRD0005 headers and decodes data payloads, and symmetrically serializes headers with encoded payloads. Values are exchanged as Double in file linear order (sizes[0] = fastest axis). The core layer performs no file IO — assembly APIs return bytes and strings only.

    #Current scope (v0.1)

    • Types: int8 / uint8 / int16 / uint16 / int32 / uint32 / float / double (int64 / uint64 explicitly rejected — beyond Double 2^53 value carrier)
    • Encodings: raw (little/big endian), ascii; attached / detached data files
    • Read: strict magic line match (NRRD0005 only); standard fields normalized by alias/case and unique (duplicates rejected); key:=value custom keys follow the spec (last value wins)
    • Write: format_header / encode_data / assemble_attached / assemble_detached (no IO, symmetric attached/detached output, NRRD0005); format_keyval_line provides spec-escaped key:=value tooling
    • Write strings are ASCII-only (v1 contract): non-ASCII code points are rejected with NrrdError, never silently truncated (prevents header injection)
    • float32 semantics: stored value is the nearest binary32 (ties-to-even); ASCII special-value detection applies to the narrowed stored value (negative underflow like -1.0e-50 emits "-0.0", not "0")

    #Planned (not yet implemented)

    • crop / slice carrying real data (with space origin/directions updates)
    • world-coordinate API (world = origin + Σ idx·dir)
    • unknown-field and key:=value round-trip preservation

    #Known limitations

    • ASCII float32 decimal parsing goes decimal → binary64 → binary32 (double rounding); not correctly rounded for all decimal literals
    • ASCII numeric token length capped at 64 bytes (implementation limit, not spec)
    • Compression (hex/gzip/bzip2/block), LIST multi-file, line/byte skip, and 64-bit integers are explicitly rejected in v1
    • NaN payload/signaling bits are not preserved (semantic nan==nan only)

    #Usage

    // Parse a header + data from bytes
    let hdr = @moon-nrrd.parse_header(buf)?
    let data = @moon-nrrd.decode_data(buf, hdr)?

    // Serialize
    let header_str = @moon-nrrd.format_header(hdr)?
    let payload = @moon-nrrd.encode_data(data, hdr)?
    let attached = @moon-nrrd.assemble_attached(hdr, payload)?

    #License

    Apache-2.0

    #Reference

    NrrdError

    pub(all) suberror NrrdError {
    NrrdError(String)
    }
    Errors from NRRD header parsing and data decoding.

    NrrdHeader

    pub(all) struct NrrdHeader {
    dimension : Int
    sizes : Array[Int]
    type_name : String
    encoding : String
    endian : String?
    data_file : String?
    space : String?
    space_dimension : Int?
    space_origin : Array[Double]?
    space_directions : Array[Array[Double]?]
    space_units : Array[String]?
    labels : Array[String]?
    kinds : Array[String]?
    content : String?
    line_skip : Int
    byte_skip : Int
    }

    ascii_to_bytes

    fn ascii_to_bytes(s : String) -> Bytes raise NrrdError
    UTF-16 traversal (missing code units raise instead).

    assemble_attached

    fn assemble_attached(h : NrrdHeader, values : Array[Double], budget? : Int) -> Bytes raise NrrdError
    No file IO — the caller decides the file name and writes bytes.

    assemble_detached

    fn assemble_detached(h : NrrdHeader, values : Array[Double], budget? : Int) -> (Bytes, Bytes) raise NrrdError
    with the terminating blank line, like an attached header.

    bytes_to_ascii

    fn bytes_to_ascii(b : Bytes) -> String
    real file bytes; NRRD headers are ASCII by specification.)

    decode_data

    fn decode_data(data : Bytes, header : NrrdHeader, budget? : Int) -> Array[Double] raise NrrdError
    illegality judgment (see README.md).

    encode_data

    fn encode_data(values : Array[Double], header : NrrdHeader, budget? : Int) -> Bytes raise NrrdError
    out-of-range values (G2 v2 §7.1).

    format_directions

    fn format_directions(rows : Array[Array[Double]?]) -> String
    space directions rows joined with " | "; none for non-spatial axes.

    format_double_list

    fn format_double_list(ds : Array[Double]) -> String

    format_float

    fn format_float(d : Double) -> String
    Print a float-typed value: "nan" / "+inf" / "-inf" / "1000.0" / "1.5".

    format_header

    fn format_header(h : NrrdHeader) -> String raise NrrdError
    replayed here.

    format_int_value

    fn format_int_value(d : Double) -> String
    Print an integer-typed value without decimal point ("1000").

    format_keyval_line

    fn format_keyval_line(key : String, value : String) -> String raise NrrdError
    library is unsupported (see module doc).

    format_opt

    fn format_opt(v : String?, none_marker? : String) -> String

    format_string_list

    fn format_string_list(ss : Array[String]) -> String

    normalize_encoding

    fn normalize_encoding(e : String) -> String raise NrrdError
    Normalize an encoding descriptor to its canonical short name.

    normalize_type

    fn normalize_type(t : String) -> String raise NrrdError
    Normalize a type descriptor to its canonical short name.

    parse_header

    fn parse_header(text : String) -> NrrdHeader raise NrrdError
    only at the split_header_body entry).

    split_header_body

    fn split_header_body(data : Bytes) -> (Bytes, Bytes) raise NrrdError
    Enforces the header-length budget before returning (G2 v2 §7.2).

    validate_header

    fn validate_header(h : NrrdHeader) -> Unit raise NrrdError
    policy for incomplete spatial info — decision C).