Yalantis/uCrop · error · CImgInstanceException

atXYZC(): Empty instance.

Error message

atXYZC(): Empty instance.

What it means

CImg<T>::atXYZC(x,y,z,c) is a checked pixel accessor using Neumann boundary conditions for the X coordinate. The library throws CImgInstanceException when the image instance is empty (no pixel buffer allocated, e.g. width/height/depth/spectrum all 0), because there is no data to read from. The underscore-prefixed _atXYZC variant skips this check for performance. This overload is the non-const version returning a mutable reference.

Source

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

        (cimg::temporary(out_value)=out_value):(*this)(x,y,z,c);
    }

    //! Access to a pixel value, using Dirichlet boundary conditions \const.
    T atXYZC(const int x, const int y, const int z, const int c, const T& out_value) const {
      return (x<0 || y<0 || z<0 || c<0 || x>=width() || y>=height() || z>=depth() || c>=spectrum())?out_value:
        (*this)(x,y,z,c);
    }

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

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

    //! Access to a pixel value, using Neumann boundary conditions \const.
    const T& atXYZC(const int x, const int y, const int z, const int c) const {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "atXYZC(): Empty instance.",
                                    cimg_instance);

View on GitHub (pinned to f788b534b4)

Solutions

  1. Check img.is_empty() (or !img) before calling atXYZC and initialize or load the image first.
  2. Verify the image was actually loaded: check the return value / file path of load()/imread().
  3. Construct the image with explicit non-zero dimensions, e.g. CImg<T> img(w,h,d,s).
  4. If emptiness is impossible, call the unchecked _atXYZC() for speed — but only after validating once.

Example fix

// before
CImg<unsigned char> img;
float v = img.atXYZC(x, y, 0, 0);
// after
CImg<unsigned char> img("input.png");
if (!img.is_empty()) {
  float v = img.atXYZC(x, y, 0, 0);
}
Defensive patterns

Strategy: validation

Validate before calling

if (img.is_empty()) { /* load/allocate or bail out */ } else { T& v = img.atXYZC(x,y,z,c); }

Type guard

inline bool usable(const cimg_library::CImg<T>& img) { return !img.is_empty(); }

Try / catch

try { auto& v = img.atXYZC(x,y,z,c); } catch (cimg_library::CImgInstanceException& e) { std::cerr << e.what() << '\n'; /* load image and retry */ }

Prevention

When it happens

Trigger: Calling img.atXYZC(x,y,z,c) on a CImg instance that was default-constructed, assigned from an empty image, or whose load failed (is_empty() == true, size() == 0).

Common situations: Default-constructed CImg never assigned; imread()/load() on a missing or corrupt file silently producing an empty image; an image constructed with 0 dimensions from computed width/height; passing an uninitialized member image in a class.

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

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