Video Properties

The Video interface defines methods for customizing and controlling a video's temporal, spatial and image properties.

Figure 8. Ghost Images of Colliding Pucks

Ghost trails of pucks

Temporal Properties

A video's temporal properties fall into two categories: (1) those based on media time t in milliseconds and (2) those based on frame number n starting with 0. Each frame has a start time and a time duration dt. The sum of the durations of all frames is the video's total duration.

Commonly used methods for controlling temporal video properties are shown in Listing 9.

Listing 9. Temporal Control Methods

public void play();
public void stop();
public void reset();
public void step();
public void back();
public void setTime(double millis);
public void setRate(double rate);
public void setLooping(boolean looping);
public void setFrameNumber(int n);
public void setStartFrameNumber(int n);
public void setEndFrameNumber(int n);

Unless a video is being played without a player, it is recommended that the start frame and end frame numbers be set indirectly through the video clip rather than with the last two methods listed here. Using a video clip is the only way to skip frames in a video.

A video steps to its next frame, not the next step in the video clip. Use the VideoPlayer.step() method to step the video clip.

The actual playing time of a video depends on both its duration and the relative rate at which it plays. A rate of 1.0 plays the video at its normal rate, 2.0 at twice its normal rate, etc. Negative rates are not supported. A user may set the play rate in the clip inspector when a video panel is used.

Note: for most videos, the frame duration dt and the frames per second (fps = 1/dt) are constant from frame to frame, but there is no requirement that this be so. For this reason, there is no method that explicitly gets or sets fps.

Figure 9. VideoPropertiesApp

VideoPropertiesApp, which demonstrates the use of some of these methods, is shown above and in Listing 10.

Listing 10. VideoPropertiesApp

// create the video
Video video = null;
try {
video = new QTVideo("videos/PucksCollide.mov");
} catch(IOException ex) {}

// create the video panel
VideoPanel vidPanel = new VideoPanel(video);
vidPanel.getPlayer().setInspectorButtonVisible(true);
vidPanel.setMessage("Slow-mo, filtered, transformed");

// get the player and clip
VideoPlayer player = vidPanel.getPlayer();
VideoClip clip = player.getVideoClip();

// set some player properties
player.setReadoutType("step"); // sets readout type

// set some clip properties
clip.setStartFrameNumber(3); // also indirectly sets video start frame
clip.setStepSize(4); // also indirectly sets video end frame

// set some temporal video properties
video.setLooping(true); // turns on looping
video.setRate(0.4); // play() will be in slow motion

// set some video image properties
video.getFilterStack().addFilter(new GhostFilter());

// set some spatial video properties
video.setAngle(Math.PI / 6); // rotate counterclockwise
video.setRelativeAspect(2); // stretch the video horizontally
video.setWidth(1.3); // set width in world units to scale the video

// display the video panel in a video frame
DrawingFrame frame = new VideoFrame(vidPanel);
frame.setVisible(true);

// set up the Java and QuickTime exit mechanisms
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
QT.exitOnClose(frame);

Spatial Properties

Commonly used methods for controlling spatial video properties are shown in Listing 11 and illustrated in the Listing 10 code above.

Listing 11. Spatial Control Methods

public void setCoords(ImageCoordSystem coords);
public void setX(double x);
public void setY(double y);
public void setWidth(double width);
public void setHeight(double height);
public void setAngle(double theta);
public void setRelativeAspect(double aspect);

All of a video's spatial properties are ultimately determined by its ImageCoordSystem, which defines transformations between the video's image coordinates (imagespace) and the drawing panel's world coordinates (worldspace). ImageCoordSystem is discussed in detail in the Video Analysis section.

The x and y properties specify the world position of the video's top left corner, while the width and height specify its world dimensions. The angle in radians is measured counterclockwise from the horizontal base of the drawing panel (the world x-axis direction) to the base of the video (the video x-axis direction)

The relative aspect is the ratio of the video's world aspect ratio (width/height in world units) to its pixel aspect ratio (width/height in pixel units). In effect, a video with a relative aspect of 2.0 appears to be stretched horizontally by a factor of two. Note that for a given relative aspect, the width of a video uniquely determines its height. In other words, setting the width also sets the height (and vice-versa). Thus, only one of these two dimension properties need be set.

When a video is created, it is given default values for all of its spatial properties: x = 0, y = 0, width = pixel width, height = pixel height, angle = 0, relative aspect = 1. However, a video is not measured until one or more of those properties are set. When unmeasured, a video draws itself centered on a drawing panel.

The methods listed set the spatial properties of all frames in a video. Equivalent methods are defined for setting the properties of individual frames.

Image Properties

It is often useful to process a video image in order to suppress noise, enhance features of interest, or create effects such as ghost images. In the media framework, such image processing functions are implemented with subclasses of the abstract class Filter. Filters are added to a video's FilterStack.

Commonly used methods for accessing and filtering video images are shown in Listing 12.

Listing 12. Image Control Methods

Video methods:
public BufferedImage getImage();
public void setVisible(boolean visible);

FilterStack methods:
public FilterStack getFilterStack();FilterStack methods:
public void addFilter(Filter filter);
public void removeFilter(Filter filter);
public void clear();

Filter methods:
public BufferedImage getFilteredImage(BufferedImage sourceImage);
public void setEnabled(boolean enabled);

The getImage() method returns an image of the current video frame after the filters in its filter stack are applied. When multiple filters are added to a stack, the filtered image from each becomes the source image for the next. Filters are applied in the order they are added to the stack. Note that a filter stack is itself a filter, so useful combinations of filters can be encapsulated in a filter stack that is then treated as a single filter.

Some filters, like the Ghost filter, are applied only when the video image changes. Ghost leaves fading ghost images of moving bright objects.