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 patch image image (%u,%u,%u,%u,%p).

What it means

After checking the patch size against the instance image, matchpatch() also requires the patch window to fit inside the supplied patch image, since patches are sampled from it. If patch_width/height/depth exceeds patch_image's corresponding dimension, the library throws this CImgArgumentException reporting both the patch size and the patch image's full dimensions and data pointer.

Source

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

                           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 "
                                    "considering instance and patch image (%u,%u,%u,%u,%p).",
                                    cimg_instance,
                                    guide._width,guide._height,guide._depth,guide._spectrum,guide._data,
                                    patch_image._width,patch_image._height,patch_image._depth,patch_image._spectrum,
                                    patch_image._data);

View on GitHub (pinned to f788b534b4)

Solutions

Ensure patch_image is at least patch_width x patch_height x patch_depth in size
Reduce the patch dimensions to fit within patch_image
Resize or rebuild the patch image/atlas to accommodate the desired patch window
Use patch_depth=1 when patch_image is 2D

Example fix

// before
atlas.matchpatch(patches, 16, 16, 1); // atlas is 8x4
// after
CImg<unsigned char> bigger_atlas = atlas.get_resize(16, 16);
atlas = bigger_atlas; // or reduce patch size to fit
atlas.matchpatch(patches, 8, 4, 1);

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
  CImg<intT> matches = img.matchpatch(patch_image, pw, ph, pd);
} catch (CImgArgumentException& e) {
  std::fprintf(stderr, "patch too large for patch image: %s\n", e.what());
  // enlarge atlas or reduce patch size before retrying
}

Prevention

Record the patch atlas dimensions alongside it and validate patch size against them
Keep one shared constant for patch size used by both image and patch image paths
Use patch_depth=1 with 2D patch atlases
Rebuild the atlas if it gets cropped/resized during preprocessing

When it happens

Trigger: Calling matchpatch(patch_image, ...) where patch_width > patch_image._width, patch_height > patch_image._height, or patch_depth > patch_image._depth - e.g. a patch atlas smaller than the requested patch window, or a 2D patch image with a 3D patch depth.

Common situations: Building a patch dictionary from crops and forgetting its size, reusing patch-size constants from a different configuration, or cropping the patch image after the patch size was fixed.

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