.\" @(#) $Header: /work/projects/tove/cvs/src/testing/vic-2.8-cqcam/h261_play.1,v 1.1 1998/03/02 10:24:52 jturunen Exp $ (LBL)
.\"
.\" Copyright (c) 1994-1995
.\" The Regents of the University of California.  
.\" All rights reserved.  
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that: (1) source code distributions
.\" retain the above copyright notice and this paragraph in its entirety, (2)
.\" distributions including binary code include the above copyright notice and
.\" this paragraph in its entirety in the documentation or other materials
.\" provided with the distribution, and (3) all advertising materials mentioning
.\" features or use of this software display the following acknowledgment:
.\" ``This product includes software developed by the University of California,
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
.\" the University nor the names of its contributors may be used to endorse
.\" or promote products derived from this software without specific prior
.\" written permission.  
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  
.\"
.TH H261_PLAY 1 "04 Apr 1996"
.de HD
.sp 1.5
.B
..
.SH NAME
h261_play \- view and dump h261 files
.SH SYNOPSIS
.na
.B h261_play
[
.B \-b
]
[
.B \-C
]
[
.B \-c
.I dither
]
[
.B \-D
]
[
.B \-d
.I display
]
[
.B \-l
]
[
.B \-n
]
[
.B \-p
]
[
.B \-S
]
[
.B \-s
]
[
.B \-t
]
[
.B \-u
.I script
]
[
.B \-V
.I visual
]
.I file
.br
.ad
.SH DESCRIPTION
.LP
.I H261_play
is a quick-and-dirty diagnostic we hacked together for debugging
our h261 decoder.  The input file should be a raw h261 bit streams
(i.e., the bit stream specified in ITU recommendation H.261 minus
the framing and error correction coding from fig. 13 and sec. 5.4).
H261_play will display this bit stream and, optionally, provide a
detailed diagnostic dump of it to stdout.  Keyboard commands are
available to single step and get some interactive diagnostic output.
.SH OPTIONS
.TP
.B \-b
make the rendering window `big' (2 x CIF).  Other window size flags are
.B \-s
(small or QCIF) and
.B \-t
(tiny or 1/8 CIF).  If none of these flags is given, the window is
made CIF size.  The h261 image is scaled to to the window size.
.TP
.B \-c
On a color-mapped display, use the algorithm indicated by
.I dither
to convert video (typically represented in 24-bit YUV color space)
to the available color palette.  For monochrome and truecolor
displays, this argument is ignored.
.I dither
may be one of the following:
.nf
	ed		error-diffusion (i.e., Floyd-Steinberg) dither 
	gray		32-levels of gray
	od		a simple 4x4 ordered dither
	quantize		straight quantization
.fi
The ``od'' algorithms uses the standard 5x5x5 color cube.
Since this color palette is used by several other applications
(wb, nv, and gs), colors can be shared which avoids the use of
a private color map.
.TP
.B \-C
show changes.  The macroblocks that changed in the current frame
are display normally while the blocks that didn't change are diplayed
in a washed-out gray.  (This option is generally only useful when
you are single stepping through the file.)
.TP
.B \-d
Connect to the X server indicated by the
.I display
argument.
.TP
.B \-D
debug \- send a very verbose, block-by-block dump of the h.261
data stream to stdout.  (See below for format.)
.TP
.B \-l
`loop' \- when the input file eof is reached, it is rewound
and restarted.
.TP
.B \-n
`no rendering' \- the input file is read and decoded (and dumped
if
.B \-D
is specified) but nothing is output to the screen.  This
flag can be used to get an ascii dump of an h261 file or
to time the decoder.
.TP
.B \-p
.I Don't
pause on startup.  Normal behavior is to start up in pause mode
so a space or carriage return is required to start decode and
rendering.
.TP
.B \-s
render into a `small' (QCIF) window.
.TP
.B \-S
Don't use the X shared memory extension to convey video images
to the X server.
.TP
.B \-t
render into a `tiny' (1/8 CIF) window.
.TP
.B \-u
Source
.I script,
in addition to the compiled-in script, to build the user interface.
This is normally only useful during development.
.TP
.B \-V
Use
.I visual
as the rendering window visual.

.SH "KEYBOARD COMMANDS"
The following can be typed in the h261_play video window:
.TP
.B space
toggles run/pause.
.TP
.B "carriage return"
if paused, single steps one frame forward.
.TP
.B q
quit \- exits the program.
.TP
.B d
dump \- dumps the current frame as a PPM file to `t.ppm'
.TP
.B f
frame \- writes the current frame number on stdout.
.TP
.B "button 1"
writes the gob and macroblock number of the data under the cursor
to stdout.

.SH "DEBUGGING OUTPUT"
The debugging output consists of one line for each syntactic unit
in the h.261 file.  Most of the output should be self explanatory,
given a copy of the H.261 spec.  Two things might not be are:
.TP
    \(bu
Each line ends with a representation of the bits that make up this
syntactic unit in the form `cnt/bstring' where
.I cnt
is the number of bits in the unit and
.I bstring
is the actual bit string in hex, right adjusted with 0 fill to a multiple
of 4 bits on the left.
.TP
    \(bu
In image coef blocks (output lines that start with
.IR blk ),
all non-zero coefs are listed in the form `number:value' where
.I number
is the coef number in zig-zag order with 0 being DC and
.I value
is the 
.I dequantized
coef value.

.SH "SEE ALSO"
vic(1),
ppmtolut(1),
mkcube(1),
histtolut(1)
.LP
McCanne, Steven and Jacobson, Van.
``vic: A Flexible Framework for Packet Video''.
In proceedings of ACM Multimedia '95.
November, 1995.
.br
.SH ACKNOWLEDGMENTS
.LP
Elan Amir (elan@cs.berkeley.edu) implemented the error diffusion
dithering code and dynamic color allocation (median cut) algorithms.
Chris Goodman (goodman@sgi.com) provided valuable advice on the
error diffusion algorithm and helped debug the implementation.
.LP
Martin Vetterli (martin@diva.eecs.berkeley.edu) provided input on fast
DCT implementations.  He pointed out that Arai, Agui, and Nakajmia's
8pt 1D DCT can be used to compute scaled row and column DCTs leading to
a 80 multiply 8x8 2D DCT.
.LP
Thanks to Robert Berger (rwb@J.GP.CS.CMU.EDU) for his excellent
web page on monitor gamma and for his permission to redistribute the
gamma calibration test image (gamma.gif).
.LP
This software is based in part on the work of the Independent JPEG Group
and the Portable Video Research Group.
.LP
This work was co-sponsored by the the Lawrence Berkeley National Laboratory
and the Tenet Group of the University of California Berkeley and 
of the International Computer Science Institute.
Support was provided by
(1) an AT&T Graduate Fellowship;
(2) for Lawrence Berkeley National Laboratory: (i) the Director,
Office of Energy Research, Scientific Computing Staff, of the
U.S. Department of Energy, Contract No. DE-AC03-76SF00098,
(ii) Sun Microsystems, (iii) Digital Equipment Corporation,
and (iv) Silicon Graphics Inc.; and
(3) for the Tenet Research Group: (i) the National Science Foundation
and the Advanced Research Projects Agency (ARPA) under
Cooperative Agreement NCR-8919038 with the Corporation for
National Research Initiatives, (ii) Digital Equipment Corporation,
and (iii) Silicon Graphics Inc.
.LP
.SH AUTHOR
Steven McCanne (mccanne@ee.lbl.gov), University of California, Berkeley
and Lawrence Berkeley National Laboratory, Berkeley, CA, and
Van Jacobson (van@ee.lbl.gov),
Lawrence Berkeley National Laboratory, Berkeley, CA.
.SH BUGS
There are no contrast or brightness controls.

The error-diffsuion dithering code needs more work.
At low luminosities, strange pastel colors appear.
Blue skies are often rendered green.

It would be nice to single-step in smaller units than a frame.