What causes "linear_atX_p(): Empty instance." in Yalantis/uCrop?

Validate img.is_empty() == false before the call.

Yalantis/uCrop · error · CImgInstanceException

linear_atX_p(): Empty instance.

Error message

linear_atX_p(): Empty instance.

What it means

CImg<T>::linear_atX_p(fx,y,z,c) returns an interpolated pixel value with periodic (wrap-around) boundary conditions on the X-coordinate. It throws CImgInstanceException when the instance is empty because there is no pixel data to interpolate.

Source

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

    Tfloat _linear_atX(const float fx, const int y=0, const int z=0, const int c=0) const {
      const float
        nfx = cimg::cut(fx,0.f,width() - 1.f);
      const unsigned int
        x = (unsigned int)nfx;
      const float
        dx = nfx - x;
      const unsigned int
        nx = dx>0?x + 1:x;
      const Tfloat
        Ic = (Tfloat)(*this)(x,y,z,c), In = (Tfloat)(*this)(nx,y,z,c);
      return Ic + dx*(In - Ic);
    }

    //! Return pixel value, using linear interpolation and periodic boundary conditions for the X-coordinate.
    Tfloat linear_atX_p(const float fx, const int y=0, const int z=0, const int c=0) const {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "linear_atX_p(): Empty instance.",
                                    cimg_instance);

      return _linear_atX_p(fx,y,z,c);
    }

    Tfloat _linear_atX_p(const float fx, const int y=0, const int z=0, const int c=0) const {
      const float
        nfx = cimg::mod(fx,_width - 0.5f);
      const unsigned int
        x = (unsigned int)nfx;
      const float
        dx = nfx - x;
      const unsigned int
        nx = cimg::mod(x + 1,_width);
      const Tfloat
        Ic = (Tfloat)(*this)(x,y,z,c), In = (Tfloat)(*this)(nx,y,z,c);
      return Ic + dx*(In - Ic);

View on GitHub (pinned to f788b534b4)

Solutions

Validate img.is_empty() == false before the call.
Confirm the source image load/allocation succeeded upstream.
Assign real dimensions/data via assign(w,h,1,s) plus fill or load before interpolating.
Use the unchecked _linear_atX_p() only with a prior emptiness guarantee.

Example fix

// before
float v = img.linear_atX_p(fx);
// after
if (!img.is_empty()) {
  float v = img.linear_atX_p(fx);
}

Defensive patterns

Strategy: validation

Validate before calling

if (!img.is_empty()) { float v = img.linear_atX_p(fx); }

Type guard

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

Try / catch

try { float v = img.linear_atX_p(fx); } catch (cimg_library::CImgInstanceException& e) { std::cerr << e.what() << '\n'; }

Prevention

Load or assign data before periodic interpolation.
Assert non-empty invariants with cimg_assert or your own checks.
Check load success right after file I/O.
Do not pass default-constructed images to sampling helpers.

When it happens

Trigger: Calling linear_atX_p() on an empty CImg (never assigned, failed load, zero dimensions).

Common situations: Periodic/tileable interpolation on an image whose load failed; unwrapping images in phase-processing pipelines where the source buffer was never filled.

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/75e58bc8ffe9064a. Report an issue: GitHub.