save_dlm(): Instance is volumetric, values along Z will be…

Error message

save_dlm(): Instance is volumetric, values along Z will be unrolled in file '%s'.

What it means

save_dlm() writes a 2D table of values to a delimited (DLM) text file, which cannot represent a 3D volume. When the image has _depth>1, the library warns that Z values will be unrolled (flattened into rows) and continues, producing a file whose layout does not preserve the volume structure.

Solutions

Save volumetric data in a format that supports 3D: save_cimg(), save_analyze(), or save_tiff (multi-page).
Explicitly extract a 2D slice before DLM export: img.get_slice(z).save_dlm(filename).
Loop over z and save one DLM file per slice.
Avoid generic save() with a .dlm extension on 3D images; name the format deliberately.

Example fix

// before
volume.save_dlm("out.dlm"); // 3D data flattened
// after
for (int z = 0; z < volume.depth(); ++z)
  volume.get_slice(z).save_dlm(cimg::format("out_z%06d.dlm", z));

Defensive patterns

Strategy: validation

Validate before calling

if (img.depth() > 1) throw std::logic_error("save_dlm requires 2D image; use get_slice or another format");
img.save_dlm(path);

Type guard

bool is2D(const CImg<T>& im) { return im.depth() == 1; }

Prevention

Check image dimensions before format-dispatching saves.
Use save_cimg/save_tiff for volumetric data.
Avoid generic save() with data-format extensions on 3D images.

When it happens

Trigger: Calling CImg::save_dlm() (or save("file.dlm")) on an image where _depth > 1, i.e. a volumetric image created e.g. via load_cimg, volume data, or 3D crops.

Common situations: Saving 3D medical/volume data to DLM by accident due to wrong extension dispatch (save() choosing DLM from filename); exporting intermediate results of 3D processing; format chosen for portability without checking dimensionality.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

       \param filename Filename, as a C-string.
    **/
    const CImg<T>& save_dlm(const char *const filename) const {
      return _save_dlm(0,filename);
    }

    //! Save image as a DLM file \overloading.
    const CImg<T>& save_dlm(std::FILE *const file) const {
      return _save_dlm(file,0);
    }

    const CImg<T>& _save_dlm(std::FILE *const file, const char *const filename) const {
      if (!file && !filename)
        throw CImgArgumentException(_cimg_instance
                                    "save_dlm(): Specified filename is (null).",
                                    cimg_instance);
      if (is_empty()) { cimg::fempty(file,filename); return *this; }
      if (_depth>1)
        cimg::warn(_cimg_instance
                   "save_dlm(): Instance is volumetric, values along Z will be unrolled in file '%s'.",
                   cimg_instance,
                   filename?filename:"(FILE*)");
      if (_spectrum>1)
        cimg::warn(_cimg_instance
                   "save_dlm(): Instance is multispectral, values along C will be unrolled in file '%s'.",
                   cimg_instance,
                   filename?filename:"(FILE*)");

      std::FILE *const nfile = file?file:cimg::fopen(filename,"w");
      const T* ptrs = _data;
      cimg_forYZC(*this,y,z,c) {
        cimg_forX(*this,x) std::fprintf(nfile,"%.17g%s",(double)*(ptrs++),(x==width() - 1)?"":",");
        std::fputc('\n',nfile);
      }
      if (!file) cimg::fclose(nfile);
      return *this;
    }

View on GitHub (pinned to f788b534b4)