squashed #823

removed separate example for reading image sequences and modified starter_video.cpp to better explain the functionality of VideoCapture. I also added a bit more explanation in the documentation of the VideoCapture interface

Conflicts:
	modules/highgui/doc/reading_and_writing_images_and_video.rst
	samples/cpp/starter_video.cpp

starter_video.cpp changed CV WINDOW KEEPRATIO to just WINDOW KEEPTATIO to fix build error

starter_video.cpp hid local functions

modules/highgui/doc/reading_and_writing_images_and_video.rst

@@ -193,8 +193,8 @@ VideoCapture
 ------------
 .. ocv:class:: VideoCapture
 
-Class for video capturing from video files or cameras.
-The class provides C++ API for capturing video from cameras or for reading video files. Here is how the class can be used: ::
+Class for video capturing from video files, image sequences or cameras.
+The class provides C++ API for capturing video from cameras or for reading video files and image sequences. Here is how the class can be used: ::
 
     #include "opencv2/opencv.hpp"
 

samples/cpp/starter_video.cpp

@@ -4,31 +4,34 @@
 *  Created on: Nov 23, 2010
 *      Author: Ethan Rublee
 *
-* A starter sample for using opencv, get a video stream and display the images
+*  Modified on: April 17, 2013
+*      Author: Kevin Hughes
+*
+* A starter sample for using OpenCV VideoCapture with capture devices, video files or image sequences
 * easy as CV_PI right?
 */
-#include "opencv2/highgui/highgui.hpp"
+
+#include <opencv2/highgui/highgui.hpp>
+
 #include <iostream>
-#include <vector>
 #include <stdio.h>
 
 using namespace cv;
 using namespace std;
 
-
-
 //hide the local functions in an anon namespace
 namespace {
     void help(char** av) {
-        cout << "\nThis program justs gets you started reading images from video\n"
-            "Usage:\n./" << av[0] << " <video device number>\n"
-            << "q,Q,esc -- quit\n"
-            << "space   -- save frame\n\n"
-            << "\tThis is a starter sample, to get you up and going in a copy pasta fashion\n"
-            << "\tThe program captures frames from a camera connected to your computer.\n"
-            << "\tTo find the video device number, try ls /dev/video* \n"
-            << "\tYou may also pass a video file, like my_vide.avi instead of a device number"
-            << endl;
+        cout << "The program captures frames from a video file, image sequence (01.jpg, 02.jpg ... 10.jpg) or camera connected to your computer." << endl
+             << "Usage:\n" << av[0] << " <video file, image sequence or device number>" << endl
+             << "q,Q,esc -- quit" << endl
+             << "space   -- save frame" << endl << endl
+             << "\tTo capture from a camera pass the device number. To find the device number, try ls /dev/video*" << endl
+             << "\texample: " << av[0] << " 0" << endl
+             << "\tYou may also pass a video file instead of a device number" << endl
+             << "\texample: " << av[0] << " video.avi" << endl
+             << "\tYou can also pass the path to an image sequence and OpenCV will treat the sequence just like a video." << endl
+             << "\texample: " << av[0] << " right%%02d.jpg" << endl;
     }
 
     int process(VideoCapture& capture) {
@@ -36,31 +39,33 @@ namespace {
         char filename[200];
         string window_name = "video | q or esc to quit";
         cout << "press space to save a picture. q or esc to quit" << endl;
-        namedWindow(window_name, CV_WINDOW_KEEPRATIO); //resizable window;
+        namedWindow(window_name, WINDOW_NORMAL); //resizable window;
         Mat frame;
+
         for (;;) {
             capture >> frame;
             if (frame.empty())
                 break;
+
             imshow(window_name, frame);
-            char key = (char)waitKey(5); //delay N millis, usually long enough to display and capture input
+            char key = (char)waitKey(30); //delay N millis, usually long enough to display and capture input
+
             switch (key) {
-        case 'q':
-        case 'Q':
-        case 27: //escape key
-            return 0;
-        case ' ': //Save an image
-            sprintf(filename,"filename%.3d.jpg",n++);
-            imwrite(filename,frame);
-            cout << "Saved " << filename << endl;
-            break;
-        default:
-            break;
+            case 'q':
+            case 'Q':
+            case 27: //escape key
+                return 0;
+            case ' ': //Save an image
+                sprintf(filename,"filename%.3d.jpg",n++);
+                imwrite(filename,frame);
+                cout << "Saved " << filename << endl;
+                break;
+            default:
+                break;
             }
         }
         return 0;
     }
-
 }
 
 int main(int ac, char** av) {
@@ -70,11 +75,11 @@ int main(int ac, char** av) {
         return 1;
     }
     std::string arg = av[1];
-    VideoCapture capture(arg); //try to open string, this will attempt to open it as a video file
+    VideoCapture capture(arg); //try to open string, this will attempt to open it as a video file or image sequence
     if (!capture.isOpened()) //if this fails, try to open as a video camera, through the use of an integer param
         capture.open(atoi(arg.c_str()));
     if (!capture.isOpened()) {
-        cerr << "Failed to open a video device or video file!\n" << endl;
+        cerr << "Failed to open the video device, video file or image sequence!\n" << endl;
         help(av);
         return 1;
     }