misleading note in doc for VideoCapture::read() (Bug #2828)

Added by be rak about 12 years ago. Updated almost 10 years ago.

Status:Done Start date:2013-02-23
Priority:Normal Due date:
Assignee:Maksim Shabunin % Done:

0%
Category:documentation
Target version:3.0
Affected version:branch 'master' (3.0-dev) Operating System:Any
Difficulty: HW Platform:Any
Pull request:https://github.com/Itseez/opencv/pull/1711

Description

there's this note at the end of:

http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html#videocapture-read

it states:

"OpenCV 1.x functions cvRetrieveFrame and cv.RetrieveFrame return image stored inside the video capturing structure. It is not allowed to modify or release the image! You can copy the frame using cvCloneImage() and then do whatever you want with the copy. "

you might get the impression, that using the 2.x api might save you from that, which is not true, since VideoCapture::read(), capture >> img, all call cvRetrieveFrame internally.

short testcase:

Mat im0;
{
        VideoCapture cap(0); 
        cap >> im0;
    }  
        // capture went out of scope & got deleted
imshow("im1",im0); // padautz!

so my proposal here, skip the 1st part, which restricts it to 1.0 functionality.:

this function returns image stored inside the video capturing structure. It is not allowed to modify or release the image! You can copy the frame using cvCloneImage(), or clone() and then do whatever you want with the copy.

Associated revisions

Revision afe6b66d
Added by Vadim Pisarevsky over 10 years ago

Merge pull request #2828 from otsedom:updating_and_adding_haarcascades_mcs

History

#1
Updated by Steven Puttemans about 10 years ago

Actually I think that the notice is kind of bogus anyway. You are perfectly allowed to change the image data, but it will do very weird things to your data.
I think the message should be completely revisited. @Vadim, what do you think?

  • HW Platform set to Any
  • Operating System set to Any
  • Affected version changed from 2.4.3 to branch 'master' (3.0-dev)

#2
Updated by Maksim Shabunin almost 10 years ago

  • Assignee changed from Vadim Pisarevsky to Maksim Shabunin
  • Target version set to 3.0

#3
Updated by Maksim Shabunin almost 10 years ago

According to VideoCapture code:

bool VideoCapture::retrieve(OutputArray image, int channel)
{
    if (!icap.empty())
        return icap->retrieveFrame(channel, image);

    IplImage* _img = cvRetrieveFrame(cap, channel);
    if( !_img )
    {
        image.release();
        return false;
    }
    if(_img->origin == IPL_ORIGIN_TL)
        cv::cvarrToMat(_img).copyTo(image);
    else
    {
        Mat temp = cv::cvarrToMat(_img);
        flip(temp, image, 0);
    }
    return true;
}

The returned image is always copied to output image. So, the mentioned note is correct as it relates only to older interface. You are allowed to delete VideoCapture instance and use returned frame without any errors.

The fix was introduced here: https://github.com/Itseez/opencv/pull/1711

  • Status changed from Open to Done
  • Pull request set to https://github.com/Itseez/opencv/pull/1711

Also available in: Atom PDF