What causes "_cimg2cvmat() : Instance image is empty." in Yalantis/uCrop?

Check img.is_empty() before converting and load/assign the image first.

Yalantis/uCrop · error · CImgInstanceException

_cimg2cvmat() : Instance image is empty.

Error message

_cimg2cvmat() : Instance image is empty.

What it means

The OpenCV bridge function _cimg2cvmat() requires a non-empty CImg image to convert to a cv::Mat. When the instance image has zero dimensions (is_empty() is true, e.g. default-constructed or never loaded), CImgInstanceException is thrown before any conversion is attempted.

Source

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

#ifdef cimg_use_opencv

    // Convert a continuous cv::Mat<uchar> to a CImg<uchar>.
    static CImg<ucharT> _cvmat2cimg(const cv::Mat &src) {
      if (src.channels()==1) return CImg<ucharT>(src.ptr(),src.cols,src.rows,1,1);
      else if (src.channels()==3) { // BGR
        CImg<ucharT> res(src.cols,src.rows,1,src.channels());
        const unsigned char *ptrs = src.ptr();
        unsigned char *pR = res.data(), *pG = res.data(0,0,0,1), *pB = res.data(0,0,0,2);
        cimg_forXY(res,x,y) { *(pB++) = *(ptrs++); *(pG++) = *(ptrs++); *(pR++) = *(ptrs++); }
        return res;
      }
      return CImg<ucharT>(src.ptr(),src.channels(),src.cols,src.rows,1,true).get_permute_axes("yzcx");
    }

    // Convert a CImg<T> to a cv::Mat.
    cv::Mat _cimg2cvmat() const {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "_cimg2cvmat() : Instance image is empty.",
                                    cimg_instance);
      if (_spectrum==2)
        throw CImgInstanceException(_cimg_instance
                                    "_cimg2cvmat() : Invalid number of channels (should be '1' or '3+').",
                                    cimg_instance);
      if (_depth!=1)
        throw CImgInstanceException(_cimg_instance
                                    "_cimg2cvmat() : Invalid number of slices (should be '1').",
                                    cimg_instance);
      int mat_type = -1;
      if (pixel_type()==cimg::type<unsigned char>::string()) mat_type = CV_8UC1;
      if (pixel_type()==cimg::type<char>::string()) mat_type = CV_8SC1;
      if (pixel_type()==cimg::type<unsigned short>::string()) mat_type = CV_16UC1;
      if (pixel_type()==cimg::type<short>::string()) mat_type = CV_16SC1;
      if (pixel_type()==cimg::type<int>::string()) mat_type = CV_32SC1;
      if (pixel_type()==cimg::type<float>::string()) mat_type = CV_32FC1;
      if (pixel_type()==cimg::type<double>::string()) mat_type = CV_64FC1;

View on GitHub (pinned to f788b534b4)

Solutions

Check img.is_empty() before converting and load/assign the image first.
Verify the load call that populated the image succeeded (file existed, format supported).
Restructure code so conversion happens only after a successful load/assignment.

Example fix

// before
CImg<unsigned char> img;
cv::Mat m = img.get_cvmat(); // throws: empty
// after
CImg<unsigned char> img;
img.load("photo.png");
if (img.is_empty()) throw std::runtime_error("image failed to load");
cv::Mat m = img.get_cvmat();

Defensive patterns

Strategy: validation

Validate before calling

if (img.is_empty()) throw std::runtime_error("cannot convert: image is empty");

Try / catch

try { cv::Mat m = img.get_cvmat(); }
catch (CImgInstanceException& e) { /* handle empty-image case */ }

Prevention

Always check is_empty() after load()
Remember load() returns an empty image on failure when exception_mode is 0
Assert non-empty at pipeline boundaries

When it happens

Trigger: Calling .get_cvmat()/_cimg2cvmat() on an image that was default-constructed, on the result of a failed load() (which returns an empty image), or after assign() cleared it.

Common situations: Forgetting to check that load() succeeded (CImg returns an empty image instead of throwing when exception_mode is 0); passing a freshly constructed CImg<T> img; a pipeline stage upstream produced no output.

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