Yalantis/uCrop · error · CImgInstanceException

XYZtoLab(): Instance is not a XYZ image.

Error message

XYZtoLab(): Instance is not a XYZ image.

What it means

CImg's XYZtoLab() converts pixel values from CIE XYZ to CIE Lab color space, which requires exactly 3 channels (X, Y, Z). The library throws CImgInstanceException when the image's _spectrum (channel count) is not 3, because the conversion reads exactly three channel planes via data(0,0,0,0..2). It is an instance-state precondition check, not a per-pixel value check.

Source

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

          p1[N] = (T)cimg::cut(3.134274799724*X  - 1.617275708956*Y - 0.490724283042*Z,0,255);
          p2[N] = (T)cimg::cut(-0.978795575994*X + 1.916161689117*Y + 0.033453331711*Z,0,255);
          p3[N] = (T)cimg::cut(0.071976988401*X - 0.228984974402*Y + 1.405718224383*Z,0,255);
        }
      }
      return *this;
    }

    //! Convert pixel values from XYZ to RGB color spaces \newinstance.
    CImg<Tuchar> get_XYZtoRGB(const bool use_D65=true) const {
      return CImg<Tuchar>(*this,false).XYZtoRGB(use_D65);
    }

    //! Convert pixel values from XYZ to Lab color spaces.
    CImg<T>& XYZtoLab(const bool use_D65=true) {
#define _cimg_Labf(x) (24389*(x)>216?cimg::cbrt(x):(24389*(x)/27 + 16)/116)

      if (_spectrum!=3)
        throw CImgInstanceException(_cimg_instance
                                    "XYZtoLab(): Instance is not a XYZ image.",
                                    cimg_instance);
      const CImg<Tfloat> white = CImg<Tfloat>(1,1,1,3,255).RGBtoXYZ(use_D65);
      T *p1 = data(0,0,0,0), *p2 = data(0,0,0,1), *p3 = data(0,0,0,2);
      const longT whd = (longT)width()*height()*depth();
      cimg_pragma_openmp(parallel for cimg_openmp_if_size(whd,128))
      for (longT N = 0; N<whd; ++N) {
        const Tfloat
          X = (Tfloat)(p1[N]/white[0]),
          Y = (Tfloat)(p2[N]/white[1]),
          Z = (Tfloat)(p3[N]/white[2]),
          fX = (Tfloat)_cimg_Labf(X),
          fY = (Tfloat)_cimg_Labf(Y),
          fZ = (Tfloat)_cimg_Labf(Z);
        p1[N] = (T)cimg::cut(116*fY - 16,0,100);
        p2[N] = (T)(500*(fX - fY));
        p3[N] = (T)(200*(fY - fZ));
      }

View on GitHub (pinned to f788b534b4)

Solutions

1. Ensure the image has exactly 3 channels before calling: if (img.spectrum()!=3) img.channels(0,2) is wrong — instead convert or rebuild the image so spectrum()==3 (e.g. call RGBtoXYZ first for genuine XYZ data).
2. For grayscale sources, replicate the channel first: if (img.spectrum()==1) img = img.get_shared_channels(0,0).get_append(CImg<float>::vector(img), 'x') or construct a 3-channel image explicitly.
3. For 4-channel (RGBA) images, strip alpha into a separate image and convert only the RGB portion.
4. Wrap in try/catch on CImgInstanceException to surface a clear message instead of crashing in JNI/native code.

Example fix

// before
img.XYZtoLab(); // throws if img.spectrum()!=3 (e.g. grayscale logo)
// after
if (img.spectrum()==1) img = CImg<float>(img.width(),img.height(),1,3).draw_image(0,0,img).draw_image(1,0,img).draw_image(2,0,img);
img.XYZtoLab();

cimg_library::CImg<float> img = source.get_channels(0, source.spectrum() >= 3 ? 2 : source.spectrum()-1);
if (img.spectrum() != 3) { /* handle */ }

template<class T> bool has3Channels(const cimg_library::CImg<T>& i){ return i.spectrum()==3; }

try { img.XYZtoLab(); } catch (cimg_library::CImgInstanceException& e) { /* repair */ }

When it happens

Trigger: Calling img.XYZtoLab() (or the RGBtoXYZ->XYZtoLab chain, or get_XYZtoLab()) on an image whose _spectrum != 3, e.g. a grayscale (_spectrum==1), RGBA (_spectrum==4), or multi-spectral image. Also triggered by chaining XYZtoLab after a conversion that did not yield 3 channels.

Common situations: Loading a grayscale PNG/JPG and applying color conversions directly; forgetting that an alpha channel makes _spectrum 4; applying XYZtoLab twice (second time the image is already Lab); building images with append_channels that produced the wrong channel count.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• LabtoXYZ(): Instance is not a Lab image.
• XYZtoxyY(): Instance is not a XYZ image.
• xyYtoXYZ(): Instance is not a xyY image.
• RGBtoYCbCr(): Instance is not a RGB image.
• YCbCrtoRGB(): Instance is not a YCbCr image.

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