Yalantis/uCrop · error · CImgArgumentException

displacement(): Instance and reference image (%u,%u,%u,%u,%p

Error message

displacement(): Instance and reference image (%u,%u,%u,%u,%p) have different dimensions.

What it means

CImg's displacement() performs optical-flow estimation between the image instance and a reference image. It requires both images to have identical width, height, depth and spectrum (is_sameXYZC); otherwise it throws this CImgArgumentException, printing the reference image's dimensions and data pointer to help identify which image mismatched.

Source

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

       tells for each pixel if its correspondence vector is constrained to its initial value (constraint mask).
    **/
    CImg<T>& displacement(const CImg<T>& reference, const float smoothness=0.1f, const float precision=5.f,
                          const unsigned int nb_scales=0, const unsigned int iteration_max=10000,
                          const bool is_forward=false,
                          const CImg<floatT>& guide=CImg<floatT>::const_empty()) {
      return get_displacement(reference,smoothness,precision,nb_scales,iteration_max,is_forward,guide).
        move_to(*this);
    }

    //! Estimate displacement field between two images \newinstance.
    CImg<floatT> get_displacement(const CImg<T>& reference,
                                  const float smoothness=0.1f, const float precision=5.f,
                                  const unsigned int nb_scales=0, const unsigned int iteration_max=1000,
                                  const bool is_forward=false,
                                  const CImg<floatT>& guide=CImg<floatT>::const_empty()) const {
      if (is_empty() || !reference) return +*this;
      if (!is_sameXYZC(reference))
        throw CImgArgumentException(_cimg_instance
                                    "displacement(): Instance and reference image (%u,%u,%u,%u,%p) have "
                                    "different dimensions.",
                                    cimg_instance,
                                    reference._width,reference._height,reference._depth,reference._spectrum,
                                    reference._data);
      if (precision<0)
        throw CImgArgumentException(_cimg_instance
                                    "displacement(): Invalid specified precision %g "
                                    "(should be >=0)",
                                    cimg_instance,
                                    precision);

      const bool is_3d = reference._depth>1;
      const unsigned int spectrum_U = is_3d?3:2;

      if (guide &&
          (guide._width!=_width || guide._height!=_height || guide._depth!=_depth || guide._spectrum<spectrum_U))
        throw CImgArgumentException(_cimg_instance

View on GitHub (pinned to f788b534b4)

Solutions

Resize the reference to match the instance with reference.resize(_width,_height,_depth,_spectrum) before calling displacement()
Match channel counts, e.g. convert both images to grayscale with get_norm().normalize() or get_channel(0)
Verify dimensions with if (!img.is_sameXYZC(reference)) before calling and handle the mismatch explicitly
Check upstream loading/cropping code so both images come from identically-sized sources

Example fix

// before
CImg<float> flow = img.displacement(reference);
// after
if (!img.is_sameXYZC(reference))
  reference.resize(img.width(), img.height(), img.depth(), img.spectrum());
CImg<float> flow = img.displacement(reference);

Defensive patterns

Strategy: validation

Validate before calling

if (!img.is_sameXYZC(reference)) {
  reference.resize(img.width(), img.height(), img.depth(), img.spectrum());
}
CImg<float> flow = img.displacement(reference);

Type guard

template<typename T>
bool isCompatibleReference(const CImg<T>& inst, const CImg<T>& ref) {
  return !inst.is_empty() && ref && inst.is_sameXYZC(ref);
}

Try / catch

try {
  CImg<float> flow = img.displacement(reference);
} catch (CImgArgumentException& e) {
  std::fprintf(stderr, "dimension mismatch: %s\n", e.what());
  reference.resize(img.width(), img.height(), img.depth(), img.spectrum());
  CImg<float> flow = img.displacement(reference);
}

Prevention

Always check is_sameXYZC(reference) before optical flow
Keep both frames from the same resolution pipeline (avoid mixed letterboxing)
Match channel counts (grayscale vs RGB) before displacement
For video, assert frame dimensions are constant across the sequence

When it happens

Trigger: Calling displacement(reference, ...) where reference has different dimensions than the instance - e.g. a reference frame from a resized video, a grayscale reference for an RGB instance (spectrum 1 vs 3), or a 3D volume paired with a 2D image (depth 1 vs >1).

Common situations: Video pipelines where frames vary in size (letterboxing), color/grayscale mismatch between frames, comparing images from different sources with different resolutions, or forgetting that a previously loaded image was cropped/rescaled.

Related errors

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