save_png(): Instance has pixel values in [%g,%g], probable t

Error message

save_png(): Instance has pixel values in [%g,%g], probable type overflow in file '%s'.

What it means

Warning from CImg<T>::save_png() when the pixel value range does not fit the target PNG bit depth: negative values present, max >= 256 for 8-bit output, or max >= 65536 for 16-bit. During conversion to the png_byte/png_uint_16 buffers values are truncated, producing clipped or wrapped output. The save itself succeeds.

Source

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

      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;
      png_error_ptr user_error_fn = 0, user_warning_fn = 0;
      png_structp png_ptr = png_create_write_struct(PNG_LIBPNG_VER_STRING,user_error_ptr, user_error_fn,
                                                    user_warning_fn);
      if (!png_ptr){
        if (!file) cimg::fclose(nfile);
        throw CImgIOException(_cimg_instance
                              "save_png(): Failed to initialize 'png_ptr' structure when saving file '%s'.",
                              cimg_instance,
                              nfilename?nfilename:"(FILE*)");
      }
      png_infop info_ptr = png_create_info_struct(png_ptr);
      if (!info_ptr) {

View on GitHub (pinned to f788b534b4)

Solutions

Normalize: img.normalize(0,255) before save_png (or 0,65535 for 16-bit)
Clamp with img.cut(0,255) to keep scale and trim outliers
Shift negatives into range if the data allows
Use a floating-point-capable format (PFM, TIFF, .cimg) instead

Example fix

// before
img.save_png("out.png"); // float [0,1]
// after
img.get_normalize(0,255).save_png("out.png");

Defensive patterns

Strategy: validation

Validate before calling

double mn, mx = img.max_min(mn);
if (mn < 0 || mx >= 256) img.normalize(0,255); // then save_png

Try / catch

// cimg::warn does not throw; check the value range before writing

Prevention

Normalize or cut values to 0-255 before save_png
Check img.min()/img.max() before encode
Use 16-bit PNG or float formats for wider ranges

When it happens

Trigger: Calling save_png() with bytes_per_pixel==1 and stmax>=256, or bytes_per_pixel==2 and stmax>=65536, or any negative stmin (from max_min() computed just before the check).

Common situations: Saving float [0,1] images without scaling (all-black output), filtered images with negative values, or >16-bit scientific data to PNG.

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/e66e563d46338bf8. Report an issue: GitHub.