Summary
The XStream® HDVR® SDK provides a set of classes that allows the user to create an animation sequence. This is defined as a number of keyframes, each with a unique set of RENDER_PARAMS. When the movie is generated, the produced frames are interpolated between the different RENDER_PARAMS values in each keyframe to produce a smoothly animated movie. The following three steps are needed to create a movie:
The C++ API provides three separate classes for the movie making process. The IMovieMakerKeyFrame class contains the keyframes that are defined by the application, and are used to produce the interpolated movie frames. The IMovie class contains a collection of keyframes, which together define the movie. The IMovieMaker class contains the utility methods that generate the complete movie sequence from the keyframes in an IMovie object.
The Java/.NET API provides three separate classes for the movie making process. The hdrcMovieMakerKeyFrame class contains the keyframes that are defined by the application, and are used to produce the interpolated movie frames. The hdrcMovie class contains a collection of keyframes, which together define the movie. The hdrcMovieMaker class contains the utility methods that generate the complete movie sequence from the keyframes in an hdrcMovie object.
When defining an animation it is important to understand the concept of keyframes. An animator defines a set of keyframes that marks the beginning and end of an animation sequence at specific time points in the animation. The computer then renders the keyframes, and all of the intermediate frames between the keyframes. A movie consisting of thousands of individual frames may be defined with only a handful of keyframes.
In C++, a keyframe is defined by the IMovieMakerKeyFrame::Create() method. This method takes as input parameters the RENDER_PARAMS structure that specifies the rendering state of the image to be rendered at that keyframe, a segment length in seconds defining the amount of time that will elapse between this keyframe and the next keyframe, and a member of the ENUM_MMKF_INTERPOLATION_TYPES enumeration that defines the type of interpolation that will be used to generate the intermediate frames.
// Configure a RENDER_PARAMS structure with properties for the keyframe.
RENDER_PARAMS rp;
pServerContext->LoadPreset("/data/presets/saved_preset.xml", &rp);
// Create an IMovieMakerKeyFrame object.
IMovieMakerKeyFrame* pKeyFrame = NULL;
pLibrary->CreateObject(&CLSID_MovieMakerKeyFrame, &pKeyFrame);
// Set the keyframe properties.
pKeyFrame->Create(&rp, 1.0, MMKF_INTERP_LINEAR);
In Java/.NET, a keyframe is defined by the hdrcMovieMakerKeyFrame class constructor. When the developer allocates a hdrcMovieMakerKeyFrame object, the constructor takes as input parameters the RENDER_PARAMS structure that specifies the rendering state of the image to be rendered at that keyframe, a segment length in seconds defining the amount of time that will elapse between this keyframe and the next keyframe, and an integer value that defines the type of interpolation that will be used to generate the intermediate frames. The hdrcMovieMakerKeyFrame class defines a number of static member variables that define the interpolation types. These are discussed in the technical documentation for the hdrcMovieMakerKeyFrame class.
// Configure a RENDER_PARAMS structure with properties for the keyframe.
RENDER_PARAMS rp = new RENDER_PARAMS();
serverContext.loadPreset("/data/presets/saved_preset.xml", rp);
// Create an IMovieMakerKeyFrame object
hdrcMovieMakerKeyFrame keyFrame = new hdrcMovieMakerKeyFrame(rp, 1.0, hdrcMovieMakerKeyFrame.MMKF_INTERP_LINEAR);
Assembling Keyframes into a Movie
Once defined by the IMoveMakerKeyFrame class, individual keyframes are assembled into a movie sequence with the IMovie class. Keyframes are inserted into the movie with the IMovie::InsertFrame() method. A number of other utility methods are provided for retrieving, removing and modifying keyframes, as well as utilities for setting and getting general movie properties. In addition, individual interpolated movie image frames can be generated from the keyframe data using the IMovie::GetInterpolatedFrame() method.
// Create an IMovie object.
IMovie* pMovie = NULL;
pLibrary->CreateObject(&CLSID_Movie, &pMovie);
// Add a keyframe to the movie.
pMovie->InsertFrame(pKeyFrame1, 0);
// Add another keyframe to the movie.
pMovie->InsertFrame(pKeyFrame2, 1);
Once defined by the hdrcMoveMakerKeyFrame class, individual keyframes are assembled into a movie sequence with the hdrcMovie class. Keyframes are inserted into the movie with the hdrcMovie::insertFrame() method. A number of other utility methods are provided for retrieving, removing and modifying keyframes, as well as utilities for setting and getting general movie properties. In addition, individual interpolated movie image frames can be generated from the keyframe data using the hdrcMovie::getFrame() method.
// Create a hdrcMovie object.
hdrcMovie* movie = new hdrcMovie();
// Add a keyframe to the movie.
movie.insertFrame(0, keyFrame1);
// Add another keyframe to the movie.
movie.insertFrame(1, keyFrame2);
Once all the IMoveMakerKeyFrame objects have been defined and assembled into an IMovie sequence, the IMovieMaker class is used to render the full movie sequence. A movie is rendered using the IMovieMaker::SetRenderEngineContext() and IMovieMaker::CreateMovie() methods. The IMovieMaker::SetRenderEngineContext() method sets the IRenderEngineContext object used to render the movie. The IMovieMaker::CreateMovie() method renders the movie based on the specified parameters. The first parameter is the IMovie object containing the keyframes of the movie to be rendered. The second parameter is the total number of frames to be rendered. The number of frames is the length of the movie in seconds multiplied by the desired frame rate of the movie. For example, a 7 second movie played at 30 frames per second (fps) generates 7 * 30 = 210 frames. The third and fourth parameters are the width and height of frames to be rendered. The fifth parameter is a boolean flag designating the frame quality to be generated, either medium or high quality. High quality frames will take longer to render. The sixth, seventh, and eighth parameters are the IVolumeDataContext, IOctreeContext, and IServerContext objects used to render the movie. The final parameter is an object of a class derived from the IFrameCreatedListener base class that implements the IFrameCreatedListener::FrameCreated() callback method. This method is invoked each time the rendering server delivers a movie frame to the client, and receives as input parameters the VOLVISIMAGE structure containing the frame data and the RENDER_PARAMS structure used to define the frame. The IFrameCreatedListener::FrameCreated() method can be used to render the frames for onscreen playback or to save to disk.
// In a header file, define a class derived from IFrameCreatedListener.
class UserFrameCreatedListener : public IFrameCreatedListener {
signed int FrameCreated(VOLVISIMAGE *pImage, RENDER_PARAMS *pState) {
// Process the received frames.
}
};
.
// In main program code, create the movie.
.
// Create an IMovieMaker object.
IMovieMaker* pMovieMaker = NULL;
pLibrary->CreateObject(&CLSID_MovieMaker, &pMovieMaker);
// Create an object of an IFrameCreatedListener derived class.
UserFrameCreatedListener frameListener;
// Set the IRenderEngineContext object used to render the movie.
pMovieMaker->SetRenderEngineContext(pRenderEngine);
// Get the number of frames in the movie.
int numFrames = pMovie->GetNumFrames();
// We will render the movie at 30 frames per second.
int totalFrames = numFrames * 30;
// Render a movie at 30 frames per second, each frame is 1024 x 1024 pixels, high quality image.
pMovieMaker->CreateMovie(pMovie, totalFrames, 1024, 1024, H_FALSE, pVolumeData, pOctreeData, pServer, &frameListener);
Once all the hdrcMoveMakerKeyFrame objects have been defined and assembled into a hdrcMovie sequence the hdrcMovieMaker class is used to render the full movie sequence. A movie is rendered using the hdrcMovieMaker::createMovie() method. The hdrcMovieMaker::createMovie() method renders the movie based on the specified parameters.. The first parameter is the hdrcMovie object containing the keyframes of the movie to be rendered. The second parameter is the total number of frames to be rendered. The number of frames is the length of the movie in seconds multiplied by the desired frame rate of the movie. For example, a 7 second movie played at 30 frames per second (fps) generates 7 * 30 = 210 frames. The third and fourth parameters are the width and height of frames to be rendered. The fifth parameter is a boolean flag designating the frame quality to be generated, either medium or high quality. High quality frames will take longer to render. The sixth, seventh, and eighth parameters are the hdrcVolumeDataContext, hdrcOctreeContext, and hdrcServerContext objects used to render the movie. The final parameter is an object of a class derived from the hdrcFrameCreatedListener base class that implements the hdrcFrameCreatedListener::frameCreated() callback method. This method is invoked each time the rendering server delivers a movie frame to the client and receives as input parameters the VOLVISIMAGE structure containing the frame data and the RENDER_PARAMS structure used to define the frame. The hdrcFrameCreatedListener::frameCreated() method is used to render the frames for onscreen playback or to save to disk.
// Define a class derived from hdrcFrameCreatedListener.
class UserFrameCreatedListener : public hdrcFrameCreatedListener {
signed int frameCreated(VOLVISIMAGE image, RENDER_PARAMS state) {
// Process the received frames.
}
};
.
// In main program code, create the movie.
.
// Create an IMovieMaker object.
hdrcMovieMaker* movieMaker = new hdrcMovieMaker()
// Create an object of an IFrameCreatedListener derived class.
UserFrameCreatedListener frameListener = new UserFrameCreatedListener();
// Get the number of frames in the movie.
int numFrames = movie.getNumFrames();
// We will render the movie at 30 frames per second.
int totalFrames = numFrames * 30;
// Render a movie at 30 frames per second, each frame is 1024 x 1024 pixels, high quality image.
movieMaker.createMovie(movie, totalFrames, 1024, 1024, FALSE, volumeData, octreeData, server, frameListener);
