Yalantis/uCrop · error · CImgInstanceException

atNXYZ(): Empty instance.

Error message

atNXYZ(): Empty instance.

What it means

Non-const CImgList<T>::atNXYZ(pos,x,y,z,c=0) accesses a pixel with Neumann boundary conditions on the 4 coordinates (pos,x,y,z) (c defaults to 0). It throws CImgInstanceException when the list instance is empty.

Source

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

    }

    //! Access pixel value with Dirichlet boundary conditions for the 3 coordinates (\c pos, \c x,\c y,\c z) \const.
    T atNXYZ(const int pos, const int x, const int y, const int z, const int c, const T& out_value) const {
      return (pos<0 || pos>=width())?out_value:_data[pos].atXYZ(x,y,z,c,out_value);
    }

    //! Access to pixel value with Neumann boundary conditions for the 4 coordinates (\c pos, \c x,\c y,\c z).
    /**
       \param pos Index of the image element to access.
       \param x X-coordinate of the pixel value.
       \param y Y-coordinate of the pixel value.
       \param z Z-coordinate of the pixel value.
       \param c C-coordinate of the pixel value.
       \note <tt>list.atNXYZ(p,x,y,z,c);</tt> is equivalent to <tt>list[p].atXYZ(x,y,z,c);</tt>.
    **/
   T& atNXYZ(const int pos, const int x, const int y, const int z, const int c=0) {
      if (is_empty())
        throw CImgInstanceException(_cimglist_instance
                                    "atNXYZ(): Empty instance.",
                                    cimglist_instance);

      return _atNXYZ(pos,x,y,z,c);
    }

    //! Access to pixel value with Neumann boundary conditions for the 4 coordinates (\c pos, \c x,\c y,\c z) \const.
    T atNXYZ(const int pos, const int x, const int y, const int z, const int c=0) const {
      if (is_empty())
        throw CImgInstanceException(_cimglist_instance
                                    "atNXYZ(): Empty instance.",
                                    cimglist_instance);

      return _atNXYZ(pos,x,y,z,c);
    }

    T& _atNXYZ(const int pos, const int x, const int y, const int z, const int c=0) {
      return _data[cimg::cut(pos,0,width() - 1)].atXYZ(x,y,z,c);

View on GitHub (pinned to f788b534b4)

Solutions

1. Check list.is_empty() (or size()>0) before sampling.
2. Verify list population succeeded before the sampling loop.
3. Prefer iterating with cimglist_for which naturally skips empty lists.
4. Catch CImgInstanceException where empty input is acceptable.

Example fix

// before
CImgList<T> lst;
double s = lst.atNXYZ(0, x, y, z);
// after
CImgList<T> lst;
if (!lst.is_empty()) {
  double s = lst.atNXYZ(0, x, y, z);
}

// C++
if (!list.is_empty()) { /* call atNXYZ safely */ }

template <typename T>
bool nonEmpty(const CImgList<T>& l) { return l.size() > 0; }

// C++
try {
  T v = list.atNXYZ(p, x, y, z);
} catch (CImgInstanceException& e) {
  // handle empty list
}

When it happens

Trigger: Calling list.atNXYZ(p,x,y,z) on an empty CImgList (is_empty()==true), typically one that was never filled or was cleared.

Common situations: 3D volume sampling helpers operating on lists loaded from files that failed to load; loops over multiple images where all images were removed; APIs that return an empty list on error and are then sampled.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• atNXYZC(): Empty instance.
• atNXY(): Empty instance.
• atNX(): Empty instance.
• atN(): Empty instance.
• cimg::mod(): Specified modulo value is 0.

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