{"record":{"id":"cc1e494ead7ad069","repo":"Yalantis/uCrop","slug":"load-video-file-s-arguments-first-frame","errorCode":null,"errorMessage":"load_video() : File '%s', arguments 'first_frame', 'last_frame' and 'step_frame' requires features from the OpenCV library ('-Dcimg_use_opencv' must be defined).","messagePattern":"load_video\\(\\) : File '(.+?)', arguments 'first_frame', 'last_frame' and 'step_frame' requires features from the OpenCV library \\('-Dcimg_use_opencv' must be defined\\)\\.","errorType":"exception","errorClass":"CImgArgumentException","httpStatus":null,"severity":"error","filePath":"ucrop/src/main/jni/CImg.h","lineNumber":67313,"sourceCode":"\n      if (!file) cimg::fclose(nfile);\n      return *this;\n    }\n\n    //! Load an image from a video file, using OpenCV library.\n    /**\n      \\param filename Filename, as a C-string.\n      \\param first_frame Index of the first frame to read.\n      \\param last_frame Index of the last frame to read (can be higher than the actual number of frames, e.g. '~0U').\n      \\param step_frame Step value for frame reading.\n      \\note If step_frame==0, the current video stream is forced to be released (without any frames read).\n    **/\n    CImgList<T>& load_video(const char *const filename,\n                            const unsigned int first_frame=0, const unsigned int last_frame=~0U,\n                            const unsigned int step_frame=1) {\n#ifndef cimg_use_opencv\n      if (first_frame || last_frame!=~0U || step_frame>1)\n        throw CImgArgumentException(_cimglist_instance\n                                    \"load_video() : File '%s', arguments 'first_frame', 'last_frame' \"\n                                    \"and 'step_frame' requires features from the OpenCV library \"\n                                    \"('-Dcimg_use_opencv' must be defined).\",\n                                    cimglist_instance,filename);\n      return load_ffmpeg_external(filename);\n#else\n      static cv::VideoCapture *captures[32] = {};\n      static CImgList<charT> filenames(32);\n      static CImg<uintT> positions(32,1,1,1,0);\n      static int last_used_index = -1;\n\n      // Detect if a video capture already exists for the specified filename.\n      cimg::mutex(9);\n      int index = -1;\n      if (filename) {\n        if (last_used_index>=0 && !std::strcmp(filename,filenames[last_used_index])) {\n          index = last_used_index;\n        } else cimglist_for(filenames,l) if (filenames[l] && !std::strcmp(filename,filenames[l])) {","sourceCodeStart":67295,"sourceCodeEnd":67331,"githubUrl":"https://github.com/Yalantis/uCrop/blob/f788b534b48c144edf786c8cddbf0e029e637804/ucrop/src/main/jni/CImg.h#L67295-L67331","documentation":"CImgList::load_video() throws this CImgArgumentException when the frame-selection arguments first_frame, last_frame or step_frame are used with values other than their defaults, but the library was compiled without OpenCV support. Frame-range video seeking is only implemented through the OpenCV cv::VideoCapture backend, guarded by the 'cimg_use_opencv' compile-time define. Without it, load_video falls back to an external ffmpeg call that can only decode the whole video from frame 0.","triggerScenarios":"Calling load_video(filename, first_frame>0) or with last_frame != ~0U or step_frame > 1 on a CImg build compiled without cimg_use_opencv (the default for a bare CImg.h drop-in).","commonSituations":"Developers copy CImg.h into an Android NDK jni folder (like ucrop does) without enabling OpenCV in the build, then try to extract a sub-range of frames from a video; or they upgrade CImg and the OpenCV define used previously is no longer set in CMake/ndk-build flags.","solutions":["Compile the native code with -Dcimg_use_opencv and link against OpenCV (libopencv_videoio) so load_video can use cv::VideoCapture.","If OpenCV support cannot be added, call load_video(filename) with default arguments (0, ~0U, 1) to load the whole video, then slice the frames in memory.","Decode with an external tool beforehand (e.g. ffmpeg -vf select) into images, then load those with CImg instead of relying on frame-range arguments."],"exampleFix":"// before\nCImgList<unsigned char> frames;\nframes.load_video(\"clip.mp4\", 10, 50, 2); // throws without cimg_use_opencv\n\n// after\nCImgList<unsigned char> frames;\nframes.load_video(\"clip.mp4\");            // decode all frames\nfor (unsigned int i = 10; i <= 50 && i < frames.size(); i += 2) {\n  CImg<unsigned char> f = frames[i]; // slice in memory\n}","handlingStrategy":"validation","validationCode":"#ifndef cimg_use_opencv\n// frame-range args unsupported: only call with defaults\nbool canUseFrameRange = false;\n#else\nbool canUseFrameRange = true;\n#endif\nif (!canUseFrameRange && (first || last != ~0U || step > 1)) {\n  // avoid frame-range arguments; use defaults\n}","typeGuard":"bool frameRangeSupported() {\n#ifdef cimg_use_opencv\n  return true;\n#else\n  return false;\n#endif\n}","tryCatchPattern":"try {\n  list.load_video(file, first, last, step);\n} catch (CImgArgumentException&) {\n  list.load_video(file); // whole-video fallback\n  // slice frames manually\n}","preventionTips":["Compile with -Dcimg_use_opencv and link OpenCV whenever you need frame-range video loading.","Wrap load_video in a helper that ignores frame args when OpenCV support is absent.","Check the define at compile time (static_assert or #ifdef) near the call site."],"tags":["cimg","opencv","compile-time-flag","video","argument-validation"],"backgroundTag":"feature-not-enabled","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"}