{"record":{"id":"eda99b1177050f97","repo":"Yalantis/uCrop","slug":"displacement-specified-guide-u-u-u-u-p-h","errorCode":null,"errorMessage":"displacement(): Specified guide (%u,%u,%u,%u,%p) has invalid dimensions.","messagePattern":"displacement\\(\\): Specified guide \\(%u,%u,%u,%u,%p\\) has invalid dimensions\\.","errorType":"validation","errorClass":"CImgArgumentException","httpStatus":null,"severity":"error","filePath":"ucrop/src/main/jni/CImg.h","lineNumber":45977,"sourceCode":"        throw CImgArgumentException(_cimg_instance\n                                    \"displacement(): Instance and reference image (%u,%u,%u,%u,%p) have \"\n                                    \"different dimensions.\",\n                                    cimg_instance,\n                                    reference._width,reference._height,reference._depth,reference._spectrum,\n                                    reference._data);\n      if (precision<0)\n        throw CImgArgumentException(_cimg_instance\n                                    \"displacement(): Invalid specified precision %g \"\n                                    \"(should be >=0)\",\n                                    cimg_instance,\n                                    precision);\n\n      const bool is_3d = reference._depth>1;\n      const unsigned int spectrum_U = is_3d?3:2;\n\n      if (guide &&\n          (guide._width!=_width || guide._height!=_height || guide._depth!=_depth || guide._spectrum<spectrum_U))\n        throw CImgArgumentException(_cimg_instance\n                                    \"displacement(): Specified guide (%u,%u,%u,%u,%p) \"\n                                    \"has invalid dimensions.\",\n                                    cimg_instance,\n                                    guide._width,guide._height,guide._depth,guide._spectrum,guide._data);\n      const float\n        scale_factor = 2.f,\n        abs_smoothness = cimg::abs(smoothness),\n        _precision = (float)std::pow(10.,-(double)precision);\n      const unsigned int\n        min_siz = is_3d?cimg::min(_width,_height,_depth):std::min(_width,_height),\n        _nb_scales = nb_scales>0?nb_scales:(unsigned int)cimg::round(std::log(min_siz)/std::log(scale_factor)) - 1;\n\n      float sm, sM = reference.max_min(sm), im, iM = max_min(im);\n      const float sdelta = sm==sM?1:(sM - sm), idelta = im==iM?1:(iM - im);\n\n      CImg<floatT> U, C;  // U: vector field, C: constraints field (at current scale)\n      for (int scale = (int)_nb_scales - 1; scale>=0; --scale) {\n        const float fact = (float)std::pow(scale_factor,(double)scale);","sourceCodeStart":45959,"sourceCodeEnd":45995,"githubUrl":"https://github.com/Yalantis/uCrop/blob/f788b534b48c144edf786c8cddbf0e029e637804/ucrop/src/main/jni/CImg.h#L45959-L45995","documentation":"displacement() accepts an optional guide image used to guide the flow estimation. The guide must match the instance image's width, height and depth, and have a spectrum of at least 2 (or 3 for 3D volumes), because it stores flow vector components. If the guide is non-empty but violates these constraints, the library throws this CImgArgumentException.","triggerScenarios":"Calling displacement(reference, ..., guide) with a guide that has different width/height/depth than the instance, a scalar (1-channel) guide, or a 3D case where guide._spectrum < 3.","commonSituations":"Reusing an output flow field from a previous run on a different-sized image, passing a single-channel image as a guide when vector components are required, or 2D/3D mismatch where the guide was built for the wrong dimensionality.","solutions":["Ensure guide has the same width/height/depth as the instance image","Ensure guide._spectrum >= 2 for 2D (>= 3 for 3D) - typically the guide is a previous flow result with exactly that many channels","Resize/recreate the guide with guide.assign(_width,_height,_depth,spectrum_U) or resize() before calling","Pass a default-constructed empty CImg (CImg<floatT>::const_empty()) if you do not want guidance, since empty guides are skipped"],"exampleFix":"// before\nCImg<float> guide(img.width(), img.height(), 1, 1); // 1 channel\ncimg_forXY(img,i,j) guide(i,j) = prior(i,j);\nCImg<float> flow = img.displacement(ref, 0.1f, 5.f, 0, 1000, false, guide);\n// after\nCImg<float> guide(img.width(), img.height(), 1, 2); // >=2 channels for 2D flow\nguide.get_shared_channel(0) = prior_x; guide.get_shared_channel(1) = prior_y;\nCImg<float> flow = img.displacement(ref, 0.1f, 5.f, 0, 1000, false, guide);","handlingStrategy":"validation","validationCode":"const unsigned int spectrum_U = reference._depth > 1 ? 3 : 2;\nif (guide && (guide._width != img._width || guide._height != img._height ||\n              guide._depth != img._depth || guide._spectrum < spectrum_U)) {\n  guide.resize(img.width(), img.height(), img.depth(), spectrum_U);\n}\nCImg<float> flow = img.displacement(reference, 0.1f, 5.f, 0, 1000, false, guide);","typeGuard":"template<typename T>\nbool isGuideValid(const CImg<T>& inst, const CImg<T>& guide) {\n  const unsigned int minS = inst._depth > 1 ? 3 : 2;\n  return !guide || (guide._width == inst._width && guide._height == inst._height &&\n                    guide._depth == inst._depth && guide._spectrum >= minS);\n}","tryCatchPattern":"try {\n  CImg<float> flow = img.displacement(reference, 0.1f, 5.f, 0, 1000, false, guide);\n} catch (CImgArgumentException& e) {\n  std::fprintf(stderr, \"invalid guide: %s\\n\", e.what());\n  CImg<float> flow = img.displacement(reference); // run without guidance\n}","preventionTips":["Guides are usually prior flow fields: keep spectrum >= 2 (2D) or >= 3 (3D)","Re-resize the guide whenever the instance image is resized/cropped","Pass an empty CImg when guidance is not needed instead of a placeholder image","Store guides together with the image dimensions they were computed for"],"tags":["cimg","image-dimensions","guide-image"],"backgroundTag":"shape-mismatch","analyzedSha":"f788b534b48c144edf786c8cddbf0e029e637804","analyzedAt":"2026-09-08T08:36:04.887Z","contentChangedAt":"2026-09-08T08:36:04.887Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}