IBM Books

Image, Audio, and Video Extenders Administration and Programming

Cataloging shots

You can store information about a shot in a shot catalog. The Video Extender provides APIs to:

Cataloged shots provide input for storyboards: After you store shot information in a shot catalog (whether the catalog is in a database or a file), you can use that information in a shot-related application. For example, you can create an application that gets the representative frames for all the shots in a video and displays them in a storyboard.

You only need to create a shot catalog for a database: You need to create a shot catalog only if you want the catalog to reside in a database. The Video Extender automatically creates a shot catalog file when you store data for the shots in a video and indicate that you want the output in a file.

Before you create a catalog (database only)

Before you create and use a catalog in a database, you must:

Creating a shot catalog (database only)

Use the DBvCreateShotCatalog API to create a shot catalog in a database. (The Video Extender automatically creates a shot catalog file when you store data for the shots and indicate that you want the output in a file.). The catalog consists of tables that store shot-related information. You can query a view of the tables by using SQL. The following table shows the columns in the view.

Table 12. Columns in the shot catalog view
Column name Data type Description
SHOTHANDLE CHAR(36) Shot handle
VIDEOHANDLE VARCHAR(254) Video handle. This column contains a value only if the video is opened with the DBvOpenHandle API.
VIDEOTABLE VARCHAR(254) Table that contains the video. This column contains a value only if the video is opened with the DBvOpenHandle API.
VIDEOCOLUMN VARCHAR(254) Table column that contains the video. This column contains a value only if the video is opened with the DBvOpenHandle API.
VIDEOFILE VARCHAR(254) Video file name. This column contains a value only if the video is opened with the DBvOpenFile API.
STARTFRAME INTEGER Starting frame number
ENDFRAME INTEGER Ending frame number
REPFRAME INTEGER Representative frame number
REPFRAMEDATA DB2IMAGE Representative frame data
COMMENTS LONG VARCHAR Comment

You have flexibility in how many shot catalogs you create in a database and for which shots you store information in each shot catalog. You can create one catalog to store shot information for many videos, have shot information for each video stored in a separate catalog, or store information for multiple shots within a video in multiple catalogs.

When you use the API, you need to specify a name for the catalog. Names larger than 16 characters are truncated. You also need to specify the database connection handle that is returned by the SQLConnect call to the database. For example, the following statements create a shot catalog that is named hotshots:

SQLHDBC  hdbc;
 
rc = SQLConnect(hdbc,"hotshots",SQL_NTS,id,SQL_NTS,password,SQL_NTS);
 
rc=DBvCreateShotCatalog(
                "hotshots",           /* shot catalog name */
                hdbc);                /* database connection handle */

Shot catalog views are named MMDBSYS.SVcatname, where catname is the name of the shot catalog. For example, a view of the catalog that is named hotshots is named MMDBSYS.SVHOTSHOTS.

Storing information about a single shot (database only)

Use the DBvInsertShot API to store information about a single shot in a shot catalog. You can store information for a single shot in a video only if the shot catalog is in a database. The information stored in the catalog includes:

A comment, however, is not stored for the shot. See Specifying a comment for a shot (database only) for a description of how you can add a comment to the information that is stored for a shot.

When you use the DBvInsertShot API, you need to specify the shot catalog name and a pointer to the shot. One way to set the pointer to the shot is to get the next shot as described in Getting a shot. You also need to specify the database connection handle that is returned by the SQLConnect call to the database. For example, the following statements get the next shot after frame 1 and then store information about the shot in a shot catalog that is named hotshots:

SQLHDBC  hdbc;
SQLHENV  henv;
DBvIOType    *video;
long start_frame = 1;
char shotDetected = 0;
DBvShotControl    shotCtrl;
DBvShotType    shot;
 
shotCtrl>method=DETECT_CORRHIST
shotCtrl>normalCorrValue=60;
shotCtrl>sceneCutSkipXY=1;
shotCtrl>CorrHistThresh=10;
shotCtrl>DissThresh=10;
shotCtrl>DissCacheSize=4;
shotCtrl>DissNumCaches=7;
shotCtrl>minShotSize=0;
 
SQLAllocConnect(henv,&hdbc)
 
rc = SQLConnect(hdbc,"hotshots",SQL_NTS,id,SQL_NTS,password,SQL_NTS);
 
rc=DBvDetectShot(
       video,
       start_frame,
       &shotDetected,
       &shotCtrl,
       &shot)
        
rc=DBvInsertShot (
       "hotshots",                /*shot catalog name*/
       shot,                      /*pointer to shot*/
       hdbc);                     /*database connection handle*/

Storing information about all the shots in a video

Use the DBvBuildStoryboardTable API or the DBvBuildStoryboardFile API to store in a shot catalog information for all the shots in a video. The DBvBuildStoryboardTable API stores the information in a shot catalog that resides in a database. The DBvBuildStoryboardFile API creates a shot catalog file and stores the shot information in the file.

For either API, the source video can be in a database table or in a file.

When you use either API, you need to:

For the DBvBuildStoryboardTable API only, you also need to specify the database connection handle that is returned by the SQLConnect call to the database.

For example, the following statements store in a shot catalog information for all the shots in a video. The shot catalog is in a database.

SQLHDBC  hdbc;
SQLHENV  henv;
DBvIOType    *video;
DBvShotControl    shotCtrl;
DBvStoryBoardCtrl    sbCtrl;
 
sbCtrl>thresh1=50
sbCtrl>thresh2=500;
sbCtrl>delta=20;
 
SQLAllocConnect(henv,&hdbc)
 
rc = SQLConnect(hdbc,"hotshots",SQL_NTS,id,SQL_NTS,password,SQL_NTS);
 
rc=DBvBuildStoryboardTable (
       "hotshots",                /*shot catalog name*/
       video,                     /*pointer to video structure*/ 
       shotCtrl,                  /*pointer to shot control structure*/
       sbctrl,                    /*pointer to storyboard control structure*/
       hdbc);                     /*database connection handle*/

The following statements create a shot catalog file and store in the file information for all the shots in a video.

DBvIOType    *video;
DBvShotControl    shotCtrl;
DBvStoryBoardCtrl    sbCtrl;
 
sbCtrl>thresh1=50
sbCtrl>thresh2=500;
sbCtrl>delta=20;
 
rc=DBvBuildStoryboardFile (
       "hotshots",                /*shot catalog file name*/
       video,                     /*pointer to video structure*/ 
       shotCtrl,                  /*pointer to shot control structure*/
       sbctrl);                   /*pointer to storyboard control structure*/     

Building a storyboard

As their name implies, the DBvBuildStoryboardTable API and DBvBuildStoryboardFile API are particularly useful for storing information to be used in a storyboard. A storyboard is a visual summary of a video. You can create a storyboard by displaying the representative frames that are stored for a video in a shot catalog.

The DBvBuildStoryboardTable API and DBvBuildStoryboardFile API store one or more representative frames for a shot. Values that you specify in the DBvStoryboardCtrl structure control the number of representative frames that are stored for a shot and which frames will be used. See Shot detection data structures for the definition of the DBvStoryboardCtrl structure. The following figure illustrates how the values in the DBvStoryboardCtrl fields are used.

Figure 23. How values in the DBvStoryboardCtrl structure are used


REQTEXT


As the figure illustrates:

Any shot can be processed as a short shot if the thresh1 or thresh2 value is set to -1. In this case, only one representative frame, the middle frame, will be stored for the shot in the shot catalog.

In addition to the values in the DBvStoryboardCtrl data structure, a number of fields in the DBvShotControl data structure impact which representative frames are stored for subsequent display in a storyboard. For example, the CorrHistThresh, normalcorrValue, and minShotSize fields in the DBvShotControl data structure specify thresholds for shot detection, and thus affect what frames will be displayed in a storyboard of a video. When you use the DBvBuildStoryBoardTable API and DBvBuildStoryBoardFile API to store shot information for use in a storyboard, you might first do a trial run using initial settings for the DBvStoryBoardCtrl and DBvShotControl data structures. You can then tune your results by changing the values in various fields of these data structures.

Displaying a storyboard

You can create a program to display a storyboard. You do this by accessing the representative frames that are stored in a shot catalog for a video. If the DBvBuildStoryboardFile API was used to store the shots for the video, the shot catalog file points to GIF files for the representative frames. You can display these GIF files using a browser or display program as appropriate.

If the DBvBuildStorybBoardTable API was used to store the shots for the video, the shot catalog (stored in a database) contains data for the representative frames. You can access the representative frame data in the shot catalog view (see Table 12 for a description of the view). The representative frame data is in YUV format; this is not a format that is displayable by most image display programs. To display the representative frames, you can convert the frame data using the DBvFrameDatato24BitRGB API as described in Displaying a retrieved frame. You can then display the representative frames using a browser or display program as appropriate.

Storyboard sample programs

The SAMPLES subdirectory contains two sample programs that demonstrate building and displaying a storyboard for a video. One sample program, in file makesf.exe, uses the DBvBuildStoryBoardFile API to create a shot catalog file and store shot data in the file. The other sample program,makehtml.exe, accesses the shot catalog file and creates HTML pages for display by a Web browser.

Specifying a comment for a shot (database only)

You can specify a comment to be stored with the other information for a shot in a shot catalog. Use the DBvSetShotComment API to specify the comment.

When you use the API, you need to specify the name of the shot catalog to store the comment, the handle of the shot for which the comment is being added, and the comment. You also need to specify the database connection handle that is returned by the SQLConnect call to the database. For example, the following statements add a comment for a shot (which starts at frame number 85) in a shot catalog that is named hotshots:

SQLHDBC  hdbc;
SQLHENV  henv;
char shothandle[37];
 
SQLAllocConnect(henv,&hdbc)
 
rc = SQLConnect(hdbc,"hotshots",SQL_NTS,id,SQL_NTS,password,SQL_NTS);
 
EXEC SQL SELECT SHOTHANDLE INTO :shothandle
  FROM MMDBSYS.SVHOTSHOTS
  WHERE STARTFRAME=85;
 
rc=DBvSetShotComment (
        "hotshots",                      /*shot catalog name*/
        shothandle,                      /*shot handle*/
        "shot of beach at sunset",       /*comment*/
        hdbc);                           /*database connection handle*/

Changing the information that is stored for a shot (database only)

You can change the information that is stored for a shot in a shot catalog. To do that, use the DBvUpdateShot API. Put the replacing information in a DBvShotType structure. You also need to specify information for the remaining fields, even if they are unchanged. When you use the DBvUpdateShot API, specify the name of the catalog and a pointer to the DBvShotType structure. You also need to specify the database connection handle that is returned by the SQLConnect call to the database.

When you change the information for the shot, you have the option of changing the comment (if any) stored with the information. If you want to change the comment, specify it in the DBvShotType structure. If you want to keep the old comment, specify a null value in the DBvShotType structure.

For example, the following statements change the information that is stored for a shot in a catalog that is named hotshots; the shot begins at frame number 85:

SQLHDBC  hdbc;
SQLHENV  henv;
char shothandle[37];
DBvShotType    shot;
DBvFrameData  fd110;
 
/* get shot handle */
 
EXEC SQL SELECT SHOTHANDLE INTO :shothandle
  FROM MMDBSYS.SVHOTSHOTS
  WHERE STARTFRAME=85;
 
/* change shot attribute */
 
shot.startFrame=110;
shot.endFrame=200;
shot.repframe=110;
shot.fd=fd110;
shot.comment=NULL;
 
/* update shot information */
 
SQLAllocConnect(henv,&hdbc)
 
rc = SQLConnect(hdbc,"hotshots",SQL_NTS,id,SQL_NTS,password,SQL_NTS);
 
rc=DBvUpdateShot (
        "hotshots",                     /*shot catalog name*/
        shot,                           /*shot information*/
        hdbc);                          /*database connection handle*/

Merging shot information in a shot catalog (database only)

You can merge the information that is stored for two shots in a shot catalog. When you merge shot information, you indicate an order for the merge by identifying a first shot and a second shot. The starting frame number of the first shot is stored as the starting frame number of the merged shot. The number of the largest frame between the first and second shots is stored as the ending frame number of the merged shot. A merge replaces the information stored for the first shot with the information for the merged shot; the information stored for the second shot is deleted from the shot catalog.

Use the DBvMergeShots API to merge the information for two shots in a shot catalog. When you use the API, specify the shot catalog name followed by the handle of the first and second shots to be merged. You also need to specify the database connection handle that is returned by the SQLConnect call to the database. For example, the following statements merge information stored for two shots in a catalog named hotshots; the first shot begins at frame 85, the second shot begins at frame 210:

SQLHDBC  hdbc;
SQLHENV  henv;
char shothandle1[37];
char shothandle2[37];
 
EXEC SQL SELECT SHOTHANDLE INTO :shothandle1
  FROM MMDBSYS.SVHOTSHOTS1
  WHERE STARTFRAME=85;
 
EXEC SQL SELECT SHOTHANDLE INTO :shothandle2
  FROM MMDBSYS.SVHOTSHOTS2
  WHERE STARTFRAME=210;
 
SQLAllocConnect(henv,&hdbc)
 
rc = SQLConnect(hdbc,"hotshots",SQL_NTS,id,SQL_NTS,password,SQL_NTS);
 
rc=DBvMergeShots (
        "hotshots",                    /*shot catalog name*/
        shothandle1,                   /*shot handle for first shot*/
        shothandle2,                   /*shot handle for second shot*/
        hdbc);                         /*database connection handle*/

Deleting shot information from a shot catalog (database only)

Use the DBvDeleteShot API to delete information about a shot from a shot catalog. When you use the API, specify the shot catalog name followed by the shot handle. You also need to specify the database connection handle that is returned by the SQLConnect call to the database. For example, the following statements delete information about a shot (which begins at frame number 85) in a shot catalog that is named hotshots:

SQLHDBC  hdbc;
SQLHENV  henv;
char shothandle[37];
 
EXEC SQL SELECT shothandle INTO :shothandle
  FROM mmdbsys.svhotshots
  WHERE startframe=85;
 
rc=DBvDeleteShot (
        "hotshots",                    /*shot catalog name*/
        shothandle,                    /*shot handle*/
        hdbc);                         /*database connection handle*/

Deleting a shot catalog (database only)

Use the DBvDeleteShotCatalog API to delete a shot catalog. When you use the API, specify the name of the shot catalog to be deleted and the database connection handle that is returned by the SQLConnect call to the database. For example, the following statement deletes a shot catalog that is named hotshots:

SQLHDBC  hdbc;
SQLHENV  henv;
 
rc=DBvDeleteShotCatalog (
        "hotshots",             /*shot catalog name*/
        hdbc);                  /*database connection handle*/


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]