FVVLib is a software library for reading Voxelogram’s Free-Viewpoint Video (FVV) file format. This document first gives a higher level overview of the interfaces provided by FVVLib to access FVV file data and how the interfaces are organized. Following this several source code examples show how the FVVLib can be used in your own application.
You can download FVVLib and a collection of FVV files from our download page.
This section shortly introduces the main interfaces provided to control FVV file loading and to access the data contained in a FVV file.
FVVLoader is the central interface in FVVLib. It is used for opening and closing FVV files, seeking in files and retrieving -Info and -Data interfaces as well as error information.
All interface functions of FVVLoader follow the same basic rules:
The purpose of the -Info and -Data interfaces is to encapsulate access to metadata and frame data that has been loaded by the FVVLoader. They do not perform any operations by themselves and their interface function do not return error codes but instead return the data directly. All pointers to -Info and -Data interface objects returned by a FVVLoader and held by clients will be valid beyond the lifetime of the FVVLoader instance that allocated them. The raw data pointers managed by the -Info and -Data shared pointers should never be deleted or manipulated by client code directly.
The interfaces with the “-Info” suffix provide access to metadata information.
FVVInfo is the main interface for accessing FVV metadata information. The interface is passed to FVVLoader::OpenFile() when opening a FVV file and after successfully opening the file can be used to access FVV file metadata through the FVVFileInfo interface as well as FVV frame metadata through the FVVFrameInfo interface.
The FVVFileInfo interface provides access to file metadata.
The interfaces with the “-Data” suffix provide access to the actual frame data.
FVVFrameData is the main interface to access the data of a particular frame. As mentioned earlier the geometry and texture format information of frames can be accessed through the FVVFrameInfo interface.
The FVVMeshData interface provides access to the indexed triangle set mesh data. The mesh data is represented by separate arrays. The vertex array and normal array containing the positions and per vertex normals of the mesh. The index array represents the faces of the mesh. It holds sets of three indices into the vertex and normal array where each set defines a triangle. This data representation can be directly used with OpenGL’s Vertex Buffer Objects (VBO).
The FVVMultiCameraImageData interface provides access to the image buffers of the multi-camera images. The format of the images can be accessed through the FVVImageInfo interface which itself is accessible through the FVVMultiCameraInfo interface. Since in the current FVV format all camera images are required to have the same properties the format of all camera images can be accessed through a single FVVImageInfo interface. For ‘RGBA’ 4 channel images the image buffer contains combined image + silhouette data with the silhouette information in the alpha channel (foreground white and background black).
The image buffer of a specific camera image can be accessed through the FVVMultiCameraImageData::GetImageBuffer function with the camera name as argument. The number of cameras and the camera names can be retrieved from the FVVMultiCameraInfo and FVVCameraInfo interfaces respectively.
As mentioned earlier all FVVLoader interface functions return an error code of type FVVResult . The special error code FVV_OK indicates success of the operation and all other error codes indicate a failure of the operation with the specific error code detailing the reason for the failure. The available error codes with their description can be looked up at FVVResult .
The following code snippet shows the basic steps in opening a FVV file and processing all frames sequentially. The example does not deal with error handling to keep the code simple.
// Do something with frame data, like e.g. rendering.
Example 1. Basic usage of FVVLib
The first step is to create a FVVLoader object which is the main interface to access FVV file data. When opening a file by calling OpenFile() we pass a reference to an empty FVVInfo shared pointer as output parameter to the function. OpenFile() will read the FVV file header and fills the metadata information into a new FVVInfo object that is passed back through the output parameter so we can access the metadata. After reading the header information the function will start two threads internally for reading and decoding of frame data. If the function fails no threads will be started internally, the output parameter will stay unmodified and the function will return an error code indicating the failure.
In the next step we access the FVVFileInfo interface with file metadata as well as the FVVFrameInfo interface with frame metadata through the FVVInfo interface. We can use information provided by these interfaces for, e.g. initialize the rendering based on the geometry and texture format of frames in the file.
We then iterating over all frames sequentially by calling GetNextFrameData() in a loop. To check if we reached the end of the sequence or an error occurred we are comparing the return error code with FVV_OK. After retrieving the last frame of the sequence the next call to GetNextFrameData() will fail with a return code of FVV_ERROR_END_OF_SEQUENCE.
GetNextFrameData() always retrieves a pointer to the next available frame and will block the calling thread until a processed frame is available. A processed frame will only be returned one time by the function, i.e. two successive calls will always return two different processed frames.
In the last statement we close the file. This will clean up the resources allocated by the loader for the file and always has to be done before we want to open another file with the same loader.
FVVLoader provides functionality for seeking in the frame sequence.
// Seek back to first frame.
Example 2. Seeking in FVV sequence
In this example we show how to seek in a FVV sequence. After opening the file we first seek to frame position 100. The valid range of frames is indexed from 0 to [NUMBER_OF_FRAMES -1], so this call will actually return the 101th frame in the sequence. The total number of frames in a FVV file can be requested from the FVVFileInfo interface. Each frame itself has a frame number that matches with it’s index number in the sequence. We show this in the code example by asserting that the frame number and the index used for seeking are identical.
From there we starting to iterate the frames until the end of the sequence. This time we are using IsEndOfSequence() for checking the terminating condition of the iteration which will return false in its output parameter after we received the last frame.
We then seek back to the beginning of the sequence (frame index 0). This allows us to iterate the complete sequence again before we finally close the file when we are finished.
The FVVLib folder contains a Visual Studio 2010 solution with two sample projects in the ‘sample’ folder.
Demonstration of how a user can iterate a frame sequence and accesses and renders the mesh geometry in each frame.
Demonstration of how user can access the camera calibration information and access and display the multi-camera images for each frame.
Please take a look at the reference documentation and example code. If you have further question, please send an e-mail to firstname.lastname@example.org.
Copyright © 2012 Voxelogram, Inc.
All rights reserved.