Getting started

Introduction

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.

 


FVVLib Software Interfaces

This section shortly introduces the main interfaces provided to control FVV file loading and to access the data contained in a FVV file.

FVVLoader

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:

  • Every function returns an FVVResult error code indicating the success or failure of the operation.
  • If a function succeeds the return code will be FVV_OK, otherwise the reason for the failure will be indicated by one of the other error codes defined in FVVResult .
  • Input parameters are passed by value, const pointer or const reference to the function.
  • Return values are passed as output parameters to a function.
  • For the output parameters pointers are used to indicate explicitly to the client that they may be modified (e.g. IsEndOfSequence(&val) vs. IsEndOfSequence(val)).

Info and Data Interfaces

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.

Info Interfaces

The interfaces with the “-Info” suffix provide access to metadata information.

FVVInfo

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.

FVVFileInfo

The FVVFileInfo interface provides access to file metadata.

  • File path
  • File size
  • File version
  • Number of frame
  • Frames per second
  • Playing time
  • Bitrate
  • Custom metadata
FVVFrameInfo

The FVVFrameInfo interface provides access to frame metadata which describes the format of the geometry and texture data available through the FVVFrameData interface.

  • Texture Format

    Data Interfaces

    The interfaces with the “-Data” suffix provide access to the actual frame data.

    FVVFrameData

    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.

    FVVMeshData

    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).

     

    Figure 1: Indexed Triangle Set Mesh

    FVVMeshData can be accessed by calling FVVFrameData::GetMeshData() if the geometry format is FVV_GEOMETRY_FORMAT_MESH.

    FVVMultiCameraImageData

    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.

    FVVMultiCameraImageData::GetImageBuffer can be accessed through FVVFrameData::GetMultiCameraImageData() if the texture format is FVV_TEXTURE_FORMAT_MULTI_CAMERA_IMAGES.

    Error Codes

    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 .

     


     

    How to use FVVLib

    Example 1: Basic usage

    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.

    #include "FVVLoader.h" 

    using fvv::FVVLoader;
    using fvv::FVVLoaderPtr;
    using fvv::FVVFileInfoPtr;
    using fvv::FVVFrameInfoPtr;
    using fvv::FVVFrameDataPtr;
    using fvv::FVVResult;

    FVVLoaderPtr loader(new FVVLoader());

    // Open FVV file.
    FVVInfoPtr fvvInfo = nullptr;
    FVVResult result = loader->OpenFile("example.fvv", &fvvInfo);

    // Get metadata interfaces.
    FVVFileInfoPtr fileInfo = fvvInfo->GetFileInfo();
    FVVFrameInfoPtr frameInfo = fvvInfo->GetFrameInfo();

    // Loop until end of sequence.
    FVVFrameDataPtr frameData = nullptr;
    while((result = loader->GetNextFrameData(&frameData)) == fvv::FVV_OK )
    {

    // Do something with frame data, like e.g. rendering.

    }

    // Close FVV file.
    result = loader->CloseFile();

     

    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.

     

    Example 2: Seeking

    FVVLoader provides functionality for seeking in the frame sequence.

    #include "FVVLoader.h" 

    using fvv::FVVLoader;
    using fvv::FVVLoaderPtr;
    using fvv::FVVFrameDataPtr;
    using fvv::FVVResult;

    ...

    FVVLoaderPtr loader( new FVVLoader() );

    // Open FVV file.
    FVVInfoPtr fvvInfo = nullptr;
    FVVResult result = loader->OpenFile("example.fvv", &fvvInfo);

    // Seek to frame at index 100. If succeeds it returns true.
    result = loader->SeekFrame(100);

    // Get frame at index 100.
    FVVFrameDataPtr frameData = nullptr;
    result = frame = loader->GetNextFrameData(&frameData);

    // The frame number is the same as the frame index.
    assert(index ==
    frameData->GetFrameNumber())

    // Loop until end of sequence.
    bool eof = false;
    result = loader->IsEndOfSequence(&eof);
    while( !eof )
    {

    result = loader->GetNextFrameData(&frameData);

    //Do something with frame information, like e.g. rendering.

    result = loader->IsEndOfSequence(&eof);

    }

    // Seek back to first frame.
    result = loader->SeekFrame(0);

    // Can start looping the sequence again here.

    // Close FVV file.
    result = loader->CloseFile();

    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.

     


    Sample Code

    The FVVLib folder contains a Visual Studio 2010 solution with two sample projects in the ‘sample’ folder.

    01_ViewMeshGeometry

    Demonstration of how a user can iterate a frame sequence and accesses and renders the mesh geometry in each frame.

    Figure 2: Screenshot of 01_ViewMeshGeometry

     

    02_ViewCameraImages

    Demonstration of how user can access the camera calibration information and access and display the multi-camera images for each frame.

    Figure 3: Screenshot of 02_ViewCameraImage

     


    More Information

    Please take a look at the reference documentation and example code. If you have further question, please send an e-mail to support@voxelogram.com.