Yalantis/uCrop · error · CImgArgumentException

blur_patch(): Invalid size for specified guide image (%u,%u,

Error message

blur_patch(): Invalid size for specified guide image (%u,%u,%u,%u,%p).

What it means

CImg's blur_patch() (non-local means style patch-based blur) uses the guide image as a feature source sampled at the same coordinates as the source image, so the guide must have the same width, height and depth. Mismatch throws this argument-validation error before the expensive patch search begins.

Source

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

          cimg_for_in##N##XY(res,x0,y0,x1,y1,p,q) if (p!=x || q!=y) { \
            tfloat *pQ = Q._data; cimg_forC(_guide,c) { cimg_get##N##x##N(_guide,p,q,0,c,pQ,tfloat); pQ+=N2; } \
            tfloat distance2 = 0; \
            pQ = Q._data; cimg_for(P,_pP,tfloat) { const tfloat dI = *_pP - *(pQ++); distance2+=dI*dI; } \
            distance2/=Pnorm; \
            const tfloat dx = (tfloat)p - x, dy = (tfloat)q - y, \
              alldist = distance2 + (dx*dx+dy*dy)/sigma_s2, weight = std::exp(-alldist); \
            if (weight>weight_max) weight_max = weight; \
            sum_weights+=weight; \
            cimg_forC(res,c) res(x,y,c)+=(Tfloat)weight*(*this)(p,q,c); \
          } \
          sum_weights+=weight_max; cimg_forC(res,c) res(x,y,c)+=(Tfloat)weight_max*(*this)(x,y,c); \
          if (sum_weights>1e-10) cimg_forC(res,c) res(x,y,c)/=(Tfloat)sum_weights; \
          else cimg_forC(res,c) res(x,y,c) = (Tfloat)((*this)(x,y,c)); \
    } _cimg_abort_catch_openmp2 }

      typedef _cimg_tfloat tfloat;
      if (!is_sameXYZ(guide))
        throw CImgArgumentException(_cimg_instance
                                    "blur_patch(): Invalid size for specified guide image (%u,%u,%u,%u,%p).",
                                    cimg_instance,
                                    guide._width,guide._height,guide._depth,guide._spectrum,guide._data);
      if (is_empty() || !patch_size || !lookup_size) return +*this;
      Tfloat val_min, val_max = (Tfloat)max_min(val_min);
      _cimg_abort_init_openmp;
      cimg_abort_init;

      CImg<Tfloat> res(_width,_height,_depth,_spectrum,0);
      const CImg<tfloat>
        __guide = guide?CImg<tfloat>(guide,guide.pixel_type()==cimg::type<tfloat>::string()):
                        CImg<tfloat>(*this,pixel_type()==cimg::type<tfloat>::string()),
        _guide = smoothness>0?__guide.get_blur(smoothness):__guide.get_shared();
      CImg<tfloat> P(_guide._spectrum*patch_size*patch_size*(_depth>1?patch_size:1)), Q(P);

      t guide_min = (t)0, guide_max = (t)0;
      if (sigma_r<0) guide_max = guide.max_min(guide_min);
      const float

View on GitHub (pinned to f788b534b4)

Solutions

  1. Resize the guide to match the source image's XYZ dimensions
  2. Derive the guide from the exact same image geometry
  3. Add an assert(img.is_sameXYZ(guide)) before the call

Example fix

// before
img.blur_patch(guideHalf, 4, 5, 0.1f);
// after
guideHalf.resize(img.width(), img.height(), img.depth(), -100, 3);
img.blur_patch(guideHalf, 4, 5, 0.1f);
Defensive patterns

Strategy: validation

Validate before calling

if (!img.is_sameXYZ(guide)) guide.resize(img.width(), img.height(), img.depth(), -100, 3);

Type guard

bool guideMatches(const CImg<T>& img, const CImg<t>& guide) { return img.is_sameXYZ(guide); }

Try / catch

try {
  img.blur_patch(guide, patchSize, lookupSize, sigmaSpatial);
} catch (cimg_library::CImgArgumentException& e) {
  guide.resize(img.width(), img.height(), img.depth(), -100, 3);
  img.blur_patch(guide, patchSize, lookupSize, sigmaSpatial);
}

Prevention

When it happens

Trigger: Calling img.blur_patch(guide, patch_size, lookup_size, ...) with a guide at different resolution (e.g. a denoised proxy at half size) or from a differently cropped image.

Common situations: Precomputing a guide/smoothed image at reduced resolution for performance; passing RGB guide for grayscale source is fine, but any XYZ difference is not; dimension drift after crop/resize operations.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

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