pgmfindclip 1.13

pgmfindclip project can automatically find a clipping border for a sequence of pgm images (a fine companion for transcode).

  Add it to your Download Basket!

 Add it to your Watch List!


Rate it!
send us
an update
GPL (GNU General Public License) 
Christian Vogelgsang
ROOT \ Multimedia \ Video
1 pgmfindclip Screenshot:
pgmfindclip project can automatically find a clipping border for a sequence of pgm images (a fine companion for transcode on Linux).

This tool tries to find a suitable clipping border for a series of gray images. It is very useful to automatically extract clipping values for transcoding a movie if the source frame is encoded with black bars.

A border around an image is defined by a rectangular and homogenous valued area extending from each edge of the image (e.g. the black bars around a movie frame). For each image the largest clip border is determined and the smallest common region of the image series is returned. Empty images or images with no valid clipping region are ignored.

To cope with noisy regions in the black border areas, the region finding algorithm does not simply cut away all regions with purely zero values, but it uses a threshold in the absolut gradient sum along rows and columns as a hint for the begin of real image contents.

You need a frame processing tool like transcode to actually perform the clipping operation.

The program assumes that all images have the same size!


Compile the source code with the given Makefile and place the resulting binary in your PATH.


You first have to generate a gray image sequence from your movie. The combination of the -K and -y ppm switches in transcode is very useful in this situation:

transcode .... -K -y ppm -o sample

It is very important to extract frames from different regions of the movie. It is usually a bad idea to extract the first couple of frames of a movie since they often contain a black screen or logos that would lead to wrong clipping borders. A better and still efficient solution is to pick all the files of the movie's title set (the VTSxxx.VOB files) and use the VOB mode of transcode to extract a single frame from each file (bash syntax!):

for a in *.vob; do transcode -i $a -x vob -z -K -y ppm -o sample -c 32-33 ; done

Note that I skip a couple of frames (here 32) because decoding of movie frames at the beginning of a vob file is not always possible correctly. (The set of VOB files is a locigal unit but the files itself are only splitted due to file/filesystem size constraints (=1GB)). Also note the -z option to flip the frames.

Then you can run pgmfindclip with:

pgmfindclip sample*.pgm

The clipping border is returned as a list of 4 comma separated values:

< top >,< left >,< bottom >,< right >

This is the correct syntax for the clipping option (-J) of transcode:

CLIP=`pgmfindclip sample*pgm`

transcode .... -j $CLIP ....

Constrain the result

pgmfindclip has various options to constrain the calculated clipping result. You can force that the resulting image is a multiple of a given factor. Also the border can be rounded to another factor. This is useful if you want to process the clipped image with a video coder that imposes such restrictions on the input format:

Give the modulo for the target image size with the -f option. The modulo for the border is given with -b. pgmfindclip will issue an error message if the combined aligning of frame and border is not possible. The frame size will be reduced to meet the restrictions and thus the border will be enlarged. You can swap this behaviour with the -e (expand) option. Then the frame might be larger than the determined clip region.

pgmfindclip -f 16 sample*.pgm

This example enforces a modulo of 16 in both directions.

More Features

If the black bars are not zero valued but have a value above zero then the gradient is very large at the border of the image. You can skip this test by specifying the -o (offset) option. Then the search will start n rows/columns later.
You can add a safety border to the calculated clipping region with the -s option. This is useful to skip bleeding artifacts at the border of scanned analog material.
You can visualize the found clip border with the -w option. This option will write new PGM images (*-m.pgm) with the clip border drawn as an inverted rectangle in it.

What's New in This Release:

added patch by Svante Signell (fixes a div by zero bug)

Last updated on May 26th, 2006

#clipping border #pgm images sequence #transcode companion #pgmfindclip #clipping #border #pgm

Add your review!