Yalantis/uCrop · error · CImgInstanceException

atNXYZC(): Empty instance.

Error message

atNXYZC(): Empty instance.

What it means

Non-const CImgList<T>::atNXYZC(pos,x,y,z,c) returns a mutable reference to a pixel of image at index pos with Neumann boundary clamping. It throws CImgInstanceException when the list itself is empty, before any coordinate handling happens.

Source

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

    }

    //! Access to pixel value with Dirichlet boundary conditions \const.
    T atNXYZC(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].atXYZC(x,y,z,c,out_value);
    }

    //! Access to pixel value with Neumann boundary conditions.
    /**
       \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.atNXYZC(p,x,y,z,c);</tt> is equivalent to <tt>list[p].atXYZC(x,y,z,c);</tt>.
    **/
    T& atNXYZC(const int pos, const int x, const int y, const int z, const int c) {
      if (is_empty())
        throw CImgInstanceException(_cimglist_instance
                                    "atNXYZC(): Empty instance.",
                                    cimglist_instance);

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

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

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

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

View on GitHub (pinned to f788b534b4)

Solutions

1. Check list.is_empty() before the call.
2. Ensure the list was successfully populated (check load() result / list.size()).
3. If only one image is needed, operate directly on a CImg instead of a list element.
4. Catch CImgInstanceException around the pixel access when emptiness is recoverable.

Example fix

// before
CImgList<float> imgs = load_list(path); // may fail and stay empty
imgs.atNXYZC(0, 1, 1) = 0.f;
// after
CImgList<float> imgs;
if (!imgs.load(path) || imgs.is_empty()) throw std::runtime_error("no images loaded");
imgs.atNXYZC(0, 1, 1, 0, 0) = 0.f;

// C++
if (list.is_empty()) return; // or load/reinit before atNXYZC

template <typename T>
bool canSample(const CImgList<T>& l) { return !l.is_empty(); }

// C++
try {
  list.atNXYZC(p, x, y, z, c) = v;
} catch (CImgInstanceException& e) {
  // empty list: recover or log
}

When it happens

Trigger: Calling list.atNXYZC(p,x,y,z,c) for a writable pixel on a CImgList with is_empty()==true (default-constructed or cleared list).

Common situations: Pixel-level loops written against a list that failed to load its images; modifying pixels of a list after remove_image() calls emptied it; helper functions receiving an unpopulated list.

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

• atNXYZ(): 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/86536eef474291a6. Report an issue: GitHub.