MetaImage I/O¶

Header: libxs_mhd.h

Read and write image data in the MetaImage (MHD/MHA) format. Files are compatible with ITK, ITK-SNAP, 3D Slicer, 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,
  size_t index, void* context);

Per-element callback for reading or converting image data. The value range (src_min, src_max) is available for scaling. index is the logical element index in write/read traversal order, and context is user data supplied by the caller.

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;
  void* handler_context;
  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,
  size_t index, void* context);

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,
  size_t index, void* context);

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,
  void* handler_context);

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.

When the environment variable LIBXS_MHD_PNG is set and the image is two-dimensional, an uncompressed PNG file is written alongside the MHD output (same base name, .png extension). Supported channel counts are 1 (grayscale), 3 (RGB), and 4 (RGBA) at 8-bit depth. Source data of any element type is converted to unsigned 8-bit using the built-in element conversion with automatic min/max scaling.