load_analyze(): File

Error message

load_analyze(): File '%s' defines an image with %u dimensions, reading only the 4 first.

What it means

load_analyze() supports at most 4 dimensions (x,y,z,v). When the ANALYZE header declares dim[0] > 4, the library warns and reads only the first 4 dimensions, silently ignoring the extra axes. The loaded image will be a lower-dimensional slice of the dataset than the file contains.

Solutions

Reshape/re-export the data so extra dimensions become the vector (dim[4], v) or z axis, or split the file into one image per extra-dimension index.
Load each 4D sub-volume separately by generating one file per time-point/vector component.
If you truly need >4 dims, read the header/volumes yourself and stitch into a CImg list.
Check whether a NIfTI-1 variant keeps the needed dims and use load_nii if available.

Example fix

// before
img.load_analyze("fmri5d.hdr"); // dim[0]=5, extra axis silently dropped
// after: split 5th axis into separate files, then loop
for (unsigned int t = 0; t < ntimes; ++t) { load_slice("fmri5d.hdr", t).move_to(volumes); }

Defensive patterns

Strategy: validation

Validate before calling

unsigned short dim0 = *(unsigned short*)(header + 40);
if (dim0 > 4) handleExtraDimensions(dim0);

Type guard

bool analyzeHeaderAtMost4D(const unsigned char* header348) { return *(const unsigned short*)(header348 + 40) <= 4; }

Try / catch

try { img.load_analyze(path); } catch (...) { /* fall back to per-slice loading */ }

Prevention

Inspect dim[0] before loading files from 4D+/5D sources.
Split extra axes into the v dimension or separate files at export time.
Prefer NIfTI-1 for datasets with more than 4 dimensions.

When it happens

Trigger: CImg::load_analyze() on a 5D+ ANALYZE file, e.g. dim[0]=5 (x,y,z,v,time) fMRI/4D+ exports from tools that write time or vector series as a 5th dimension.

Common situations: 4D+fMRI data with time as dim[5]; vector-valued datasets stored with an extra axis; files converted from NIfTI with >4 dims; mixing up dim[] slot order when hand-crafting headers.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/29f3f7ffdbdce87c. Report an issue: GitHub.

Appendix: source

Thrown at ucrop/src/main/jni/CImg.h:58457

        cimg::invert_endianness((float*)(header + 76),4);
        cimg::invert_endianness((float*)(header + 108),1);
        cimg::invert_endianness((float*)(header + 112),1);
      }

      if (nfile_header==nfile) {
        const unsigned int vox_offset = (unsigned int)*(float*)(header + 108);
        std::fseek(nfile,vox_offset,SEEK_SET);
      }

      unsigned short *dim = (unsigned short*)(header + 40), dimx = 1, dimy = 1, dimz = 1, dimv = 1;
      if (!dim[0])
        cimg::warn(_cimg_instance
                   "load_analyze(): File '%s' defines an image with zero dimensions.",
                   cimg_instance,
                   filename?filename:"(FILE*)");

      if (dim[0]>4)
        cimg::warn(_cimg_instance
                   "load_analyze(): File '%s' defines an image with %u dimensions, reading only the 4 first.",
                   cimg_instance,
                   filename?filename:"(FILE*)",dim[0]);

      if (dim[0]>=1) dimx = dim[1];
      if (dim[0]>=2) dimy = dim[2];
      if (dim[0]>=3) dimz = dim[3];
      if (dim[0]>=4) dimv = dim[4];
      float scalefactor = *(float*)(header + 112); if (scalefactor==0) scalefactor = 1;
      const unsigned short datatype = *(unsigned short*)(header + 70);
      if (voxel_size) {
        const float *vsize = (float*)(header + 76);
        voxel_size[0] = vsize[1]; voxel_size[1] = vsize[2]; voxel_size[2] = vsize[3];
      }
      delete[] header;

      // Read pixel data.
      assign(dimx,dimy,dimz,dimv);

View on GitHub (pinned to f788b534b4)