VideoGrabber classes
From IGSTK
Contents |
Current implementations
The igstk::Imager presents a generic interface for grabbing video from real video-devices such Ultrasound, Endoscope, Bronchoscope, etc. One igstk::Imager object can manage one or more igstk::ImagerTool objects, where the igstk::Imager object is responsible for communication and the igstk::ImagerTool is responsible for specific settings according the connected video-device. The corresponding spatial object igstk::VideoFrameSpatialObject and representation igstk::VideoFrameRepresentation are responsible for rendering the video-stream into the IGSTK scene.
Involved main classes:
igstk::Imager.h/.cxx igstk::ImagerTool.h/.cxx
Derivations of these main classes
/Source/igstkCompressedDVImager.h/.cxx /Source/igstkCompressedDVImagerTool.h/.cxx /Source/igstkImagingSourceImager.h/.cxx /Source/igstkImagingSourceImagerTool.h/.cxx /Source/igstkWebcamWinImager.h/.cxx /Source/igstkWebcamWinImagerTool.h/.cxx /Source/igstkTerasonImager.h/.cxx /Source/igstkTerasonImagerTool.h/.cxx
SpatialObject and Representation
igstk::VideoFrameSpatialObject.h/.cxx igstk::VideoFrameRepresentation.h/.cxx igstk::Frame.h/.cxx
How to use the video grabber classes
Build your own specific classes for your video device deriving from igstk::Imager and igstk::ImagerTool
If you use the device FOO then you can name the classes as follows. For this purpose use existing specifications like igstk::WebcamWinImager.h/.cxx and igstk::WebcamWinImagerTool.h/cxx and make device specific changes there.
/Source/igstkFOOImager.cxx /Source/igstkFOOImager.h /Source/igstkFOOImagerTool.cxx /Source/igstkFOOImagerTool.h
You will see that you don't have to change much. The most important changes are in igstkFOOImager.h/cxx.
Look here for example implementations: /** These device specific implementations work with compressed DV [Camcorder,Endoscope] in Linux */
/Source/igstkCompressedDVImager.cxx /Source/igstkCompressedDVImager.h /Source/igstkCompressedDVImagerTool.cxx /Source/igstkCompressedDVImagerTool.h
/** These device specific implementations work with an converter from the vendor ImagingSource in Linux */
/Source/igstkImagingSourceImager.cxx /Source/igstkImagingSourceImager.h /Source/igstkImagingSourceImagerTool.cxx /Source/igstkImagingSourceImagerTool.h
/** These device specific implementations work with conventional webcams in Windows */
/Source/igstkWebcamWinImager.cxx /Source/igstkWebcamWinImager.h /Source/igstkWebcamWinImagerTool.cxx /Source/igstkWebcamWinImagerTool.h
After creating your own video-device specific classes you can use them in the example application below in the example part of this page.
Tests
Examples
The "VideoFrameGrabberAndViewerWebcamWin" example combines all important parts of the Video component. It works with standard webcams but it can be easily changed to other video-devices. For this purpose instantiate instead of igstk::WebcamWinImager and igstk::WebcamWinImagerTool your own specializations of igstk::Imager and igstk::ImagerTool. You can also use one of the example specializations namely igstk::CompressedDVImager and igstk::CompressedDVImagerTool for video-devices working with compressed DV such several endoscopes or bronchoscopes or use igstk::ImagingSourceImager and igstk::ImagingSourceImagerTool if you own the framegrabber from vendor ImagingSource.
This small example is in IGSTKSandbox and compiles only if OpenCV is installed. The source code for this section can be found in the file:
IGSTKSandbox/Examples/VideoFrameGrabberAndViewerWebcam/VideoFrameGrabberAndViewerWebcamWin.cxx.
Source code documentation:
Define refresh rates for View and Imager.
#define VIEW_2D_REFRESH_RATE 25 #define IMAGER_DEFAULT_REFRESH_RATE 25
The GUI is implemented using FLTK. For this purpose an instance of igstk::FLTKWidget and igstk::View3D are created and connected via the method: m_VideoWidget->RequestSetView( m_VideoView ); This is done in VideoFrameGrabberAndViewerWebcamWinView.cxx. Afterwards we set up and start igstk::View3D.
// Set background color to the View m_ViewerGroup->m_VideoView->SetRendererBackgroundColor(0,0,1); // Set parallel projection to the camera m_ViewerGroup->m_VideoView->SetCameraParallelProjection(true); // Set refresh rate m_ViewerGroup->m_VideoView->SetRefreshRate( VIEW_2D_REFRESH_RATE ); // Start the View m_ViewerGroup->m_VideoView->RequestStart(); // Enable user interactions with the window m_ViewerGroup->m_VideoWidget->RequestEnableInteractions();
The geometrical description of the videoframe in the scene is managed by the videoframe SpatialObject. For this purpose we need igstk::VideoFrameSpatialObject. Since igstk::VideoFrameSpatialObject is a template class we define in the first parameter the pixeltype and in the second parameter the channel number. Here we set ”unsigned char” for pixeltype and 3 channels for RGB. We declare and instantiate then a igstk::VideoFrameSpatialObject as follows:
typedef igstk::VideoFrameSpatialObject<unsigned char, 3 > VideoFrameSpatialObjectType; VideoFrameSpatialObjectType::Pointer m_VideoFrame; We set device specific parameters in igstk::VideoFrameSpatialObject. m_VideoFrame = VideoFrameSpatialObjectType::New(); m_VideoFrame->SetWidth(320); m_VideoFrame->SetHeight(240); m_VideoFrame->SetPixelSizeX(1); m_VideoFrame->SetPixelSizeY(1); m_VideoFrame->SetNumberOfScalarComponents(3); m_VideoFrame->Initialize();
Following scene graph is implemented here: igstk::View3D - igstk::VideoFrameSpatialObject - igstk::AxesObject with identity transform for each dependency.
m_VideoFrame->RequestSetTransformAndParent( identity, m_WorldReference ); m_ViewerGroup->m_VideoView->RequestDetachFromParent(); m_ViewerGroup->m_VideoView->RequestSetTransformAndParent( identity, m_VideoFrame );
The visual Representation of SpatialObjects in the visualization window is created using SpatialObject Representation classes. The corresponding Representation class for igstk::VideoFrameSpatialObject is igstk::VideoFrameRepresentation, which is also templated and needs the igstk::VideoFrameSpatialObject as parameter. We declare and instantiate igstk::VideoFrameRepresentation as follows:
typedef igstk::VideoFrameRepresentation<VideoFrameSpatialObjectType> VideoFrameRepresentationType; VideoFrameRepresentationType::Pointer m_VideoFrameRepresentationForVideoView; m_VideoFrameRepresentationForVideoView = VideoFrameRepresentationType::New();
Add the videoframe Spatialobject to the videoframe Representation.
m_VideoFrameRepresentationForVideoView->RequestSetVideoFrameSpatialObject( m_VideoFrame );
Next, the Representation is added to the View as follows:
m_ViewerGroup->m_VideoView->RequestAddObject( m_VideoFrameRepresentationForVideoView );
We create here an Observer for the igstk::Imager. This Observer will catch all failure events generated by igstk::Imager. The ErrorObserver is implemented in VideoFrameGrabberAndViewerWebcamWin.h.
this->m_ErrorObserver = ErrorObserver::New();
The following code instantiates a new Imager object for conventional webcams. The igstk::WebcamWinImager derive from igstk::Imager and implement device specific communication. See for device specific implementations igstk::WebcamWinImager.h and igstk::WebcamWinImager.cxx
igstk::WebcamWinImager::Pointer Imager = igstk::WebcamWinImager::New();
According to connected device we set here the refresh rate
Imager->RequestSetFrequency( IMAGER_DEFAULT_REFRESH_RATE );
Before request calls to the Imager we add an observer to the Imager class in order to catch possible error events.
unsigned long observerID = m_Imager->AddObserver( IGSTKErrorEvent(),this->m_ErrorObserver );
Now, we try to open the communication with the device and retrieve for possibly occurred errors.
m_Imager->RequestOpen();
if( this->m_ErrorObserver->ErrorOccured() )
{
this->m_ErrorObserver->GetErrorMessage( this->m_ErrorMessage );
this->m_ErrorObserver->ClearError();
m_Imager->RemoveObserver(observerID);
cout << this->m_ErrorMessage << endl;
}
Next we create an igstk::WebcamWinImagerTool and set frame dimensions, pixel depth and an unique name for identification. Consider these parameters must be the same as the parameters for the igstk::VideoFrameSpatialObject After setup, the Imager tool can be configured.
ImagerTool::Pointer imagerTool;
WebcamWinImagerTool::Pointer imagerToolWebcam = WebcamWinImagerTool::New();
unsigned int dims[3];
dims[0] = 320;
dims[1] = 240;
dims[2] = 3;
imagerToolWebcam->SetFrameDimensions(dims);
imagerToolWebcam->SetPixelDepth(8);
imagerToolWebcam->RequestSetImagerToolName("Camera");
imagerToolWebcam->RequestConfigure();
Here we connect the Imager with the Imager tool
imagerTool->RequestAttachToImager( m_Imager );
After that the Imager tool can set to the videoframe Spatialobject as follows:
m_VideoFrame->SetImagerTool(imagerTool);
Here we request to start the Imager. In case of success the communication thread starts retrieving continuously frames from the device and the main application thread fills according to the pulse-generator-frequency the ringbuffer in the Imager tool.
m_Imager->RequestStartImaging();
Finally, before exiting the application, the Imager is properly closed and other clean up procedures are executed, as follows:
m_ViewerGroup->m_VideoView->RequestRemoveObject( m_VideoFrameRepresentationForVideoView ); m_ViewerGroup->m_VideoView->RequestResetCamera(); this->m_Imager->RequestStopImaging(); this->m_Imager->RequestClose();
Licence issues
The core VideoComponent is licence independent.
Video-Device specific implementations are licensed as follows:
| Class | BSD | LGPL | GPL | Libraries |
|---|---|---|---|---|
| igstkWebcamWinImager / igstkWebcamWinImagerTool | X | openCV | ||
| igstkTerasonImager / igstkTerasonImagerTool | X | OpenIGTLink | ||
| igstkCompressedDVImager / igstkCompressedDVImagerTool | X | libraw1394, libdv, libiec61883 | ||
| igstkImagingSourceImager / igstkImagingSourceImagerTool | X | unicap |
Testing data
[[Media:Media:Example.ogg]]
