Yalantis/uCrop · error · CImgArgumentException

matchpatch(): Specified patch size %ux%ux%u is bigger than t

Error message

matchpatch(): Specified patch size %ux%ux%u is bigger than the dimensions of the instance image.

What it means

In matchpatch(), the patch window (patch_width x patch_height x patch_depth) must fit inside the instance image. If any patch dimension exceeds the corresponding instance dimension, the library throws this CImgArgumentException because no valid match window could be extracted.

Source

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

                           const unsigned int patch_width,
                           const unsigned int patch_height,
                           const unsigned int patch_depth,
                           const unsigned int nb_iterations,
                           const unsigned int nb_randoms,
                           const float patch_penalization,
                           const CImg<t1> &guide,
                           const bool is_matching_score,
                           CImg<t2> &matching_score) const {
      if (is_empty()) return CImg<intT>::const_empty();
      if (patch_image._spectrum!=_spectrum)
        throw CImgArgumentException(_cimg_instance
                                    "matchpatch(): Instance image and specified patch image (%u,%u,%u,%u,%p) "
                                    "have different spectrums.",
                                    cimg_instance,
                                    patch_image._width,patch_image._height,patch_image._depth,patch_image._spectrum,
                                    patch_image._data);
      if (patch_width>_width || patch_height>_height || patch_depth>_depth)
        throw CImgArgumentException(_cimg_instance
                                    "matchpatch(): Specified patch size %ux%ux%u is bigger than the dimensions "
                                    "of the instance image.",
                                    cimg_instance,patch_width,patch_height,patch_depth);
      if (patch_width>patch_image._width || patch_height>patch_image._height || patch_depth>patch_image._depth)
        throw CImgArgumentException(_cimg_instance
                                    "matchpatch(): Specified patch size %ux%ux%u is bigger than the dimensions "
                                    "of the patch image image (%u,%u,%u,%u,%p).",
                                    cimg_instance,patch_width,patch_height,patch_depth,
                                    patch_image._width,patch_image._height,patch_image._depth,patch_image._spectrum,
                                    patch_image._data);
      const unsigned int
        _constraint = patch_image._depth>1?3:2,
        constraint = guide._spectrum>_constraint?_constraint:0;

      if (guide &&
          (guide._width!=_width || guide._height!=_height || guide._depth!=_depth || guide._spectrum<_constraint))
        throw CImgArgumentException(_cimg_instance
                                    "matchpatch(): Specified guide (%u,%u,%u,%u,%p) has invalid dimensions "

View on GitHub (pinned to f788b534b4)

Solutions

Reduce patch_width/patch_height/patch_depth so each is <= the instance image's dimensions
Compute the patch size dynamically, e.g. std::min(16u, (unsigned)img.width())
Skip or resize small images before patch matching
Use patch_depth=1 for 2D images instead of a volumetric patch size

Example fix

// before
img.matchpatch(patches, 16, 16, 1); // img is 10x10
// after
const unsigned pw = std::min(16u, (unsigned)img.width());
const unsigned ph = std::min(16u, (unsigned)img.height());
img.matchpatch(patches, pw, ph, 1);

Defensive patterns

Strategy: validation

Validate before calling

if (patch_width > img.width() || patch_height > img.height() || patch_depth > img.depth()) {
  patch_width  = std::min(patch_width,  (unsigned)img.width());
  patch_height = std::min(patch_height, (unsigned)img.height());
  patch_depth  = std::min(patch_depth,  (unsigned)img.depth());
}
CImg<intT> matches = img.matchpatch(patch_image, patch_width, patch_height, patch_depth);

Type guard

template<typename T>
bool patchFitsImage(unsigned pw, unsigned ph, unsigned pd, const CImg<T>& img) {
  return pw <= (unsigned)img.width() && ph <= (unsigned)img.height() &&
         pd <= (unsigned)img.depth();
}

Try / catch

try {
  CImg<intT> matches = img.matchpatch(patch_image, pw, ph, pd);
} catch (CImgArgumentException& e) {
  std::fprintf(stderr, "patch too large for instance: %s\n", e.what());
  CImg<intT> matches = img.matchpatch(patch_image,
      std::min(pw,(unsigned)img.width()), std::min(ph,(unsigned)img.height()), 1);
}

Prevention

Derive patch size from the smallest image in the batch, not a constant
Use patch_depth=1 for 2D images
Clamp patch dimensions with std::min against image dims
Re-check patch sizes after any downscaling preprocessing

When it happens

Trigger: Calling matchpatch() with patch_width > _width, patch_height > _height, or patch_depth > _depth - e.g. a 16x16 patch on a 10x10 image, or a 3D patch size on a 2D (depth=1) image.

Common situations: Hardcoded patch sizes larger than small thumbnails/tiles, applying 3D-volume patch parameters to 2D images, or images downscaled by preprocessing after the patch size was chosen.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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