Yalantis/uCrop · error · CImgArgumentException

blur_bilateral(): Invalid size for specified guide image (%u

Error message

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

What it means

CImg's blur_bilateral() requires the guide (range/edge) image to have exactly the same width, height and depth as the source image (spectrum may differ). The bilateral filter pairs every source pixel with a guide pixel, so mismatched sizes throw this argument-validation error.

Source

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

         Defaults (0) to sigma_x.
       \param sampling_y Amount of downsampling along the Y-axis used for the approximation.
         Defaults (0) to sigma_y.
       \param sampling_z Amount of downsampling along the Z-axis used for the approximation.
         Defaults (0) to sigma_z.
       \param sampling_r Amount of downsampling along the value axis used for the approximation.
         Defaults (0) to sigma_r.
       \note This algorithm uses the optimisation technique proposed by S. Paris and F. Durand, in ECCV'2006
       (extended for 3D volumetric images).
       It is based on the reference implementation http://people.csail.mit.edu/jiawen/software/bilateralFilter.m
    **/
    template<typename t>
    CImg<T>& blur_bilateral(const CImg<t>& guide,
                            const float sigma_x, const float sigma_y,
                            const float sigma_z, const float sigma_r,
                            const float sampling_x, const float sampling_y,
                            const float sampling_z, const float sampling_r) {
      if (!is_sameXYZ(guide))
        throw CImgArgumentException(_cimg_instance
                                    "blur_bilateral(): 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() || (!sigma_x && !sigma_y && !sigma_z)) return *this;
      T edge_min, edge_max = guide.max_min(edge_min);
      if (edge_min==edge_max) return blur(sigma_x,sigma_y,sigma_z);
      const float
        edge_delta = (float)(edge_max - edge_min),
        _sigma_x = sigma_x>=0?sigma_x:-sigma_x*_width/100,
        _sigma_y = sigma_y>=0?sigma_y:-sigma_y*_height/100,
        _sigma_z = sigma_z>=0?sigma_z:-sigma_z*_depth/100,
        _sigma_r = sigma_r>=0?sigma_r:-sigma_r*edge_delta/100,
        _sampling_x = sampling_x?sampling_x:std::max(_sigma_x,1.f),
        _sampling_y = sampling_y?sampling_y:std::max(_sigma_y,1.f),
        _sampling_z = sampling_z?sampling_z:std::max(_sigma_z,1.f),
        _sampling_r = sampling_r?sampling_r:std::max(_sigma_r,edge_delta/256),
        derived_sigma_x = _sigma_x / _sampling_x,
        derived_sigma_y = _sigma_y / _sampling_y,

View on GitHub (pinned to f788b534b4)

Solutions

  1. Resize the guide to match the source: guide.resize(img.width(), img.height(), img.depth(), -100, 3)
  2. Recompute the guide from the same-resolution source image
  3. Assert img.is_sameXYZ(guide) before calling

Example fix

// before
img.blur_bilateral(guideSmall, 8, 8, 0, 10);
// after
guideSmall.resize(img.width(), img.height(), img.depth(), -100, 3);
img.blur_bilateral(guideSmall, 8, 8, 0, 10);
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_bilateral(guide, sx, sy, sz, sr);
} catch (cimg_library::CImgArgumentException& e) {
  guide.resize(img.width(), img.height(), img.depth(), -100, 3);
  img.blur_bilateral(guide, sx, sy, sz, sr);
}

Prevention

When it happens

Trigger: Calling img.blur_bilateral(guide, ...) where guide is a grayscale downsample or differently cropped version of img; passing a guide built from another image with different dimensions.

Common situations: Using a luminance/edge guide computed after resizing; loading the guide from disk with different resolution; forgetting that guide XYZ (not necessarily spectrum) must match.

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/63de967cf1b62f84. Report an issue: GitHub.