Yalantis/uCrop · error · CImgArgumentException

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

Error message

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

What it means

The get_blur_guided() new-instance variant of the guided filter requires the guide image to match the source image's width, height and depth. If is_sameXYZ(guide) fails, CImg throws this error; the filter indexes guide pixels at the same coordinates as source pixels.

Source

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

    /**
       \param guide Image used to guide the smoothing process.
       \param radius Spatial radius. If negative, it is expressed as a percentage of the largest image size.
       \param regularization Regularization parameter.
                             If negative, it is expressed as a percentage of the guide value range.
       \note This method implements the filtering algorithm described in:
       He, Kaiming; Sun, Jian; Tang, Xiaoou, "Guided Image Filtering," Pattern Analysis and Machine Intelligence,
       IEEE Transactions on , vol.35, no.6, pp.1397,1409, June 2013
    **/
    template<typename t>
    CImg<T>& blur_guided(const CImg<t>& guide, const float radius, const float regularization) {
      return get_blur_guided(guide,radius,regularization).move_to(*this);
    }

    //! Blur image, with the image guided filter \newinstance.
    template<typename t>
    CImg<Tfloat> get_blur_guided(const CImg<t>& guide, const float radius, const float regularization) const {
      if (!is_sameXYZ(guide))
        throw CImgArgumentException(_cimg_instance
                                    "blur_guided(): 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() || !radius) return *this;
      const int _radius = radius>=0?(int)radius:(int)(-radius*cimg::max(_width,_height,_depth)/100);
      float _regularization = regularization;
      if (regularization<0) {
        T edge_min, edge_max = guide.max_min(edge_min);
        if (edge_min==edge_max) return *this;
        _regularization = -regularization*(edge_max - edge_min)/100;
      }
      _regularization = std::max(_regularization,0.01f);
      const unsigned int psize = (unsigned int)(1 + 2*_radius);
      CImg<Tfloat>
        mean_p = get_blur_box(psize,true),
        mean_I = guide.get_blur_box(psize,true).resize(mean_p),
        cov_Ip = get_mul(guide).blur_box(psize,true)-=mean_p.get_mul(mean_I),
        var_I = guide.get_sqr().blur_box(psize,true)-=mean_I.get_sqr(),

View on GitHub (pinned to f788b534b4)

Solutions

Resize the guide to the source dimensions before the call
Regenerate the guide from the same geometry as the source image
Check is_sameXYZ in code before invoking get_blur_guided

Example fix

// before
CImg<float> out = img.get_blur_guided(guideLowRes, 5, 0.01f);
// after
guideLowRes.resize(img.width(), img.height(), img.depth(), -100, 3);
CImg<float> out = img.get_blur_guided(guideLowRes, 5, 0.01f);

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 {
  auto out = img.get_blur_guided(guide, radius, regularization);
} catch (cimg_library::CImgArgumentException& e) {
  guide.resize(img.width(), img.height(), img.depth(), -100, 3);
  auto out = img.get_blur_guided(guide, radius, regularization);
}

Prevention

Resize guidance images (depth maps, edge maps) to source geometry first
Check XYZ match, not spectrum: channels may differ
Cover guided filtering with a same-size fixture test

When it happens

Trigger: Calling img.get_blur_guided(guide, radius, regularization) with a guide of different resolution or channel-count-derived dimensions, e.g. a downscaled guidance image or one loaded from another file.

Common situations: Using a guidance image (edges map, depth map, flash/no-flash pairs) captured or stored at a different size; mismatch after applying resize to one image only.

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/6fca04190cccbeec. Report an issue: GitHub.