libxs_mhd.md

MetaImage I/O

Header: libxs_mhd.h

Read and write image data in the MetaImage (MHD/MHA) format. Files are compatible with ITK-SNAP, ParaView, and similar tools.

Types

typedef enum libxs_mhd_element_conversion_hint_t {
  LIBXS_MHD_ELEMENT_CONVERSION_DEFAULT,
  LIBXS_MHD_ELEMENT_CONVERSION_MODULUS
} libxs_mhd_element_conversion_hint_t;

Hint controlling element conversion behaviour (default clamping vs. modulus mapping).

typedef struct libxs_mhd_element_handler_info_t {
  libxs_data_t type;
  libxs_mhd_element_conversion_hint_t hint;
} libxs_mhd_element_handler_info_t;

Destination type and conversion hint, passed to built-in or custom element handlers.

typedef int (*libxs_mhd_element_handler_t)(void* dst,
  const libxs_mhd_element_handler_info_t* dst_info,
  libxs_data_t src_type,
  const void* src, const void* src_min, const void* src_max);

Per-element callback for reading or converting image data. The value range (src_min, src_max) is available for scaling.

typedef struct libxs_mhd_info_t {
  size_t ndims;         /* dimensionality */
  size_t ncomponents;   /* interleaved image channels */
  libxs_data_t type;  /* pixel element type */
  size_t header_size;   /* header size in bytes (LOCAL data) */
} libxs_mhd_info_t;

Image descriptor populated by libxs_mhd_read_header and consumed by read/write.

typedef struct libxs_mhd_write_info_t {
  const libxs_mhd_element_handler_info_t* handler_info;
  libxs_mhd_element_handler_t handler;
  const char* extension_header;
  const void* extension;
  size_t extension_size;
} libxs_mhd_write_info_t;

Optional write parameters (conversion, custom handler, extension data). NULL is accepted for all-defaults.

Element Helpers

int libxs_mhd_element_conversion(void* dst,
  const libxs_mhd_element_handler_info_t* dst_info,
  libxs_data_t src_type,
  const void* src, const void* src_min, const void* src_max);

Built-in element conversion. Scales values when src_min and src_max are non-NULL; otherwise clamps to the destination type.

int libxs_mhd_element_comparison(void* dst,
  const libxs_mhd_element_handler_info_t* dst_info,
  libxs_data_t src_type,
  const void* src, const void* src_min, const void* src_max);

Check an in-memory buffer against file content (element-wise comparison with optional type conversion).

Type Queries

const char* libxs_mhd_typename(libxs_data_t type,
  const char** ctypename);

Return the MHD element-type name (e.g. "MET_FLOAT") for the given libxs_data_t. Optionally writes the C type name. Returns NULL for unknown types.

libxs_data_t libxs_mhd_typeinfo(const char elemname[]);

Return the libxs_data_t for a given MHD element-type string.

Read

int libxs_mhd_read_header(const char header_filename[],
  size_t filename_max_length, char filename[],
  libxs_mhd_info_t* info, size_t size[],
  char extension[], size_t* extension_size);

Parse an MHD header file. info->ndims is an in/out parameter (maximum on input, actual on output). filename receives the data-file path (may differ from the header when data is stored separately). Extension data is optional.

int libxs_mhd_read(const char filename[],
  const size_t offset[], const size_t size[],
  const size_t pitch[], const libxs_mhd_info_t* info,
  void* data,
  const libxs_mhd_element_handler_info_t* handler_info,
  libxs_mhd_element_handler_t handler);

Read image data into data. Optional handler_info triggers type conversion; optional handler supplies a custom per-element callback (can also serve as a comparison function without allocating a buffer).

Write

int libxs_mhd_write(const char filename[],
  const size_t offset[], const size_t size[],
  const size_t pitch[], libxs_mhd_info_t* info,
  const void* data,
  const libxs_mhd_write_info_t* write_info);

Write image data in the extended MHD format. info->header_size is updated on output. Pass NULL for write_info when no conversion or extension is needed.