Yalantis/uCrop · warning

save_png(): Instance is volumetric, only the first slice wil

Error message

save_png(): Instance is volumetric, only the first slice will be saved in file '%s'.

What it means

Warning from CImg<T>::save_png() when the image is volumetric (_depth>1). libpng writes a single 2D image, so only the first slice (z=0) is saved and the remaining slices are dropped. The save completes without an error.

Source

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

      cimg::unused(bytes_per_pixel);
      if (!file) return save_other(filename);
      else throw CImgIOException(_cimg_instance
                                 "save_png(): Unable to save data in '(*FILE)' unless libpng is enabled.",
                                 cimg_instance);
#else

#if defined __GNUC__
      const char *volatile nfilename = filename; // Use 'volatile' to avoid (wrong) g++ warning
      std::FILE *volatile nfile = file?file:cimg::fopen(nfilename,"wb");
      volatile double stmin, stmax = (double)max_min(stmin);
#else
      const char *nfilename = filename;
      std::FILE *nfile = file?file:cimg::fopen(nfilename,"wb");
      double stmin, stmax = (double)max_min(stmin);
#endif

      if (_depth>1)
        cimg::warn(_cimg_instance
                   "save_png(): Instance is volumetric, only the first slice will be saved in file '%s'.",
                   cimg_instance,
                   filename);

      if (_spectrum>4)
        cimg::warn(_cimg_instance
                   "save_png(): Instance is multispectral, only the three first channels will be saved in file '%s'.",
                   cimg_instance,
                   filename);

      if (stmin<0 || (bytes_per_pixel==1 && stmax>=256) || stmax>=65536)
        cimg::warn(_cimg_instance
                   "save_png(): Instance has pixel values in [%g,%g], probable type overflow in file '%s'.",
                   cimg_instance,
                   stmin,stmax,filename);

      // Setup PNG structures for write.
      png_voidp user_error_ptr = 0;

View on GitHub (pinned to f788b534b4)

Solutions

1. Save slices individually: cimg_for_z(img,z) img.get_slice(z).save_png(...);
2. Use save_tiff or the native .cimg format for volumes
3. Append frames to an animated PNG/APNG path if supported by the build
4. Ignore the warning if only the first slice is needed

Example fix

// before
volume.save_png("out.png");
// after
cimg_for_z(volume,z) volume.get_slice(z).save_png(cimg::format("out_%d.png",z));

if (img.depth() > 1) { /* save slices or choose another format */ }

// warning only; guard by depth check before calling save_png

When it happens

Trigger: Calling save_png() on an image with depth > 1, e.g. a volume loaded from a 3D format or constructed with a depth dimension greater than 1.

Common situations: Exporting z-stacks, CT/MRI volumes, or frame sequences (stored as depth) to PNG.

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

• save_jxl(): Instance is volumetric, only the first slice wil
• save_magick(): Instance is volumetric, only the first slice
• save_png(): Instance is multispectral, only the three first
• save_png(): Instance has pixel values in [%g,%g], probable t
• save_pnm(): Instance is volumetric, only the first slice wil

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