Yalantis/uCrop · error · CImgInstanceException

atXYZ(): Empty instance.

Error message

atXYZ(): Empty instance.

What it means

Thrown by CImg<T>::atXYZ(int,int,int,int,const T&) when the image is empty (null data / zero dimensions): even though atXYZ normally returns out_value for out-of-bounds coordinates, there is no pixel buffer at all to index, so the access is rejected.

Source

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

      return (x<0 || y<0 || z<0 || x>=width() || y>=height() || z>=depth())?
        (cimg::temporary(out_value)=out_value):(*this)(x,y,z,c);
    }

    //! Access to a pixel value, using Dirichlet boundary conditions for the X,Y and Z-coordinates \const.
    T atXYZ(const int x, const int y, const int z, const int c, const T& out_value) const {
      return (x<0 || y<0 || z<0 || x>=width() || y>=height() || z>=depth())?out_value:(*this)(x,y,z,c);
    }

    //! Access to a pixel value, using Neumann boundary conditions for the X,Y and Z-coordinates.
    /**
       Similar to atX(int,int,int,int), except that boundary checking is performed both on X,Y and Z-coordinates.
       \note
       - If you know your image instance is \e not empty, you may rather use the slightly faster method
         \c _atXYZ(int,int,int,int).
    **/
    T& atXYZ(const int x, const int y, const int z, const int c=0) {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "atXYZ(): Empty instance.",
                                    cimg_instance);
      return _atXYZ(x,y,z,c);
    }

    T& _atXYZ(const int x, const int y, const int z, const int c=0) {
      return (*this)(cimg::cut(x,0,width() - 1),
                     cimg::cut(y,0,height() - 1),
                     cimg::cut(z,0,depth() - 1),c);
    }

    //! Access to a pixel value, using Neumann boundary conditions for the X,Y and Z-coordinates \const.
    const T& atXYZ(const int x, const int y, const int z, const int c=0) const {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "atXYZ(): Empty instance.",
                                    cimg_instance);
      return _atXYZ(x,y,z,c);

View on GitHub (pinned to f788b534b4)

Solutions

1. Check img.is_empty() before calling atXYZ().
2. Verify the volume-producing step (load/assign/crop) returned non-zero dimensions.
3. Note the C coordinate is still unchecked - validate it yourself.

Example fix

// before
float v = vol.atXYZ(x, y, z); // throws if vol empty
// after
if (!vol.is_empty()) { float v = vol.atXYZ(x, y, z); }

if (!vol.is_empty() && c >= 0 && c < vol.spectrum()) {
  T v = vol.atXYZ(x, y, z, c);
}

try {
  T v = vol.atXYZ(x, y, z);
} catch (CImgInstanceException& e) {
  // empty volume fallback
}

When it happens

Trigger: Calling img.atXYZ(x,y,z,c) on an empty (zero-size) image, typically a default-constructed CImg or one from a failed load.

Common situations: Volumetric/3D sampling code where the volume failed to load or a crop produced zero depth.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• at(): Empty instance.
• atXY(): Empty instance.
• atX(): Empty instance.
• operator(): Invalid pixel request, at coordinates (%d,%d,%d,
• data(): Invalid pointer request, at coordinates (%u,%u,%u,%u

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