Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PPM2FLI(1)		    General Commands Manual		    PPM2FLI(1)

NAME
       ppm2fli - create	a FLI animation	from a set of static images

SYNOPSIS
       ppm2fli [ options ] [ list-file [ animation-file	] ]

DESCRIPTION
       The  program ppm2fli generates a	FLI/FLC-animation from a series	of im-
       ages.  The file list-file contains a list of the	names of image	files,
       one  per	 line  separated  by the new-line character.  These images are
       merged together in the supplied	order.	 The  generated	 animation  is
       written to animation-file.

       The file	formats	which can be read directly are PPM, PGM	and PBM	(ascii
       and raw:	magic 'P1' to 'P6') as	well  as  FBM  (mapped	8bpp  and  rgb
       24bpp).	 Ppm2fli  can invoke external filters which convert other file
       formats to the PPM or FBM standard.  For	example	such filters  are  in-
       cluded  in  the	PBMPLUS, NETPBM	and FBM	packages.  Together with these
       packages	a large	number of graphic formats can be handled.

       The generation of the animation is done in two separate steps:

       -  Computation of a common color	table for all images

       -  Quantization of the images and computing the FLI/FLC frames

       The first step is done by scanning all images and using a modified ver-
       sion  of	 the Octree algorithm to compute a color table from the	shades
       found in	the images.  This color	table is supposed to be	a --  more  or
       less -- best fit	to the color shades which were found in	the images.

       When  the  input	images are already quantized the result	depends	on the
       number of colors	which they use altogether.  If this number is equal or
       less  than  the	given  maximum	(default: 256),	the scanning step just
       evaluates these colors and assembles the	color table without any	 modi-
       fication.   When	 the input images contain more colors, some colors are
       put together and	assigned to an average value, until the	 total	number
       is sufficiently low.

       Alternatively  it's  possible  to  generate the color table by scanning
       only one	image, a so called map image.  It may be one  from  the	 given
       list  or	 an  extra  image.  This procedure is faster but the resulting
       color table may be less suitable	for the	other images.

       Third possibility is to do the quantization separately and generate  an
       extra  color  table for each image.  This may result in a change	of the
       color table between the frames of the FLI animation.  However, the pro-
       gram tries to keep the color table as static as possible.

       The  area of the	image that the final animation produces	when played is
       denoted as display_area.	 Default is a display_area of 640x480  pixels.
       It  is  allowed that the	size of	the input images varies.  If the width
       of an input image is greater than the width  of	the  display_area,  an
       equal  number  of  pixels is removed from each side of the input	image.
       If the width of an input	image is less  than  the  width	 of  the  dis-
       play_area,  this	 results  in the creation of a border around the image
       (default: center	the image in the display_area).	 The same is  done  in
       vertical	direction.

QUANTIZE OPTIONS
       -I     Perform  an  individual  quantize	of each	image independently of
	      all other	images.	 In this case no common	table is used  and  it
	      may occur	that new colors	are loaded between the FLI/FLC frames.
	      Usually a	common color table should  be  preferred.   Only  when
	      this  results  in	very poor quantization of the images a varying
	      color table is recommended.

       -Qc numcolors
	      Employ numcolors as the maximum number of	 colors	 used  in  the
	      quantized	 images	(range:	9-256; default:	256).  A low value may
	      result in	a poor quantization.

       -Qd bits
	      Employ bits as the color depth used in  the  color  map  of  the
	      quantized	 images	(range:	2-8; default: 8).  Lower values	reduce
	      the number of colors in the quantized images.

       -Qn nodelimit
	      Set the maximum number of	nodes that the Octree  is  allowed  to
	      have  in the second-deepest level.  A larger value may result in
	      a	better quantization but	slows down the scanning	of the images.
	      Recommended  values: between one time and	four times the numcol-
	      ors value	(range:	16-2048; default: 512).	 See section  "TECHNI-
	      CAL NOTES" for more details.

       -Qr reducelevels
	      Set  the number of levels	which are considered when reducing the
	      Octree (range: 0-8; default: 8).	See section "TECHNICAL	NOTES"
	      for more details.

       -m file
	      The  common  color table is generated by scanning	only the image
	      in the given file.  Usually this is much	faster	than  scanning
	      all images, but the color	table represents only colors which oc-
	      cur in the given image.  If this image is	not representative for
	      the others, their	quantization may become	very poor.

       -w file
	      The  generated  color  table  is	written	to the given file as a
	      256x1 PPM	ascii image.  Then the program terminates without  as-
	      sembling	the fli	animation.  Later this color table file	can be
	      used with	the `-m' option	to generate the	fli  animation.	  When
	      the  `-w'	 option	 is  given the parameter animation-file	can be
	      omitted.	If both	`-m' and `-w' are  given  also	the  parameter
	      list-file	isn't necessary.

FLI/FLC	OPTIONS
       -D     Include  additionally  update  information  with	respect	to the
	      frame before the last.  Default: generated FLI chunks  hold  up-
	      date information only for	the immediately	preceding frame.

	      In both cases, the resulting animations work with	standard play-
	      ers.  The	additional update information is  useful  for  players
	      that  use	 the  double  buffering	technique (see TECHNICAL NOTES
	      section below).

       -N     Same as `-D' but instead of the frame before the last the	update
	      information  with	 respect  to  the following frame is included.
	      This allows the play in reverse direction	with the XAnim player.
	      Note that	`-D' and `-N' exclude each other.

       -O     Generate output using the	older FLI format associated with magic
	      number 0xAF11.  Some older players cannot	handle newer FLI  ani-
	      mations associated with the magic	number 0xAF12 (these are some-
	      times known as FLC files).  Use the old LC_CHUNKS	 (12)  instead
	      of   DELTA_CHUNKS	  (7),	 and   COLOR_CHUNKS  (11)  instead  of
	      COLOR_256_CHUNKS (4), and	set default resolution to 320x200  in-
	      stead of the usual 640x480.

       -b color
	      If  a  particular	 input	image  does  not cover the entire dis-
	      play_area, employ	the specified color for	all pixels in the bor-
	      der  area.  Default: zero	(See also `+/-ox').  To	evaluate which
	      number a certain color has the `-w' option can be	used.  By that
	      the  color  table	 is written to a file (ascii) and then the de-
	      sired color can be looked	up in the table.

       -g widthxheight
	      This defines the width and height	of the	display_area  (allowed
	      range:  from  10x10  to 1280x1024).  If an odd value of width is
	      specified, it is automatically incremented by one.  A particular
	      FLI  player  may	only support a limited set of resolutions.  In
	      principle, VGA resolution	(320x200)  should  always  work.   For
	      players  supporting  the	newer  style of	FLIs (FLCs) associated
	      with the magic number 0xAF12, 640x480 should also	work.

       +/-ox hor_position
	      Disable the automatic centering of input	images	in  horizontal
	      direction.  Place	the input images at a fix position in the dis-
	      play_area.  When `+ox' is	used the left border of	the input  im-
	      ages  is kept fix	independently of the width of the images.  The
	      value gives the distance between the left	 border	 of  the  dis-
	      play_area	and the	left border of the input image.	 When `-ox' is
	      used the right border of the input  images  is  kept  fix.   The
	      value  gives  the	 distance between the right border of the dis-
	      play_area	and the	right border of	 the  input  image.   In  both
	      cases  negative  values  can  be specified.  Then	the respective
	      border of	the input images is outside of the display_area	and  a
	      part  of the images is cut off.  The option can be used to place
	      input images with	varying	width at a  certain  position  in  the
	      display_area,  or	 to  animate a certain section of larger input
	      images.

       +/-oy vert_position
	      Identical	to `+/-ox', but	controls the vertical position.	  When
	      `+oy'  is	used the number	of pixels from the upper border	of the
	      display_area to the upper	border of the  input  images  is  set.
	      Respectively  `-oy'  controls  the  position with	respect	to the
	      lower border.

       -s speed
	      Use the specified	speed to be stored in the header  of  the  FLI
	      file.   The  FLI	standard  requires  a speed value in the file.
	      Some players use this number as default when no other  speed  is
	      given.   The  meaning  of	 the speed argument depends on the FLI
	      format in	use.  Higher values reduce the speed.  For old	format
	      FLIs,  the value specifies the number of video ticks between two
	      frames (default: 5).  For	new format FLIs, the delay between two
	      frames  is  specified  in	1/1000 seconds rather than video ticks
	      (default:	72/1000	seconds, resulting in approximately 15	frames
	      per second).

GENERAL	OPTIONS
       -v     Print  internal  information  to stdout.	`-vv' causes even more
	      things to	be written.

       +/-f filter
	      Use the specified	filter when reading the	input images.  This is
	      necessary	 when  other than the default formats are used or when
	      the input	files are compressed (see the  examples	 below).   The
	      reading is done using the	popen subroutine.  If `-f' is used the
	      specified	filter is supposed to read from	 stdin.	  The  command
	      used  in	the popen statement has	the form `filter < image'.  In
	      the case of `+f' the image name if passed	 as  argument  to  the
	      filter  program.	 In both cases the filter program has to write
	      the converted image to stdout.  The option overwrites the	filter
	      defined by the environment variable PPM2FLIFILTER.

       -t     Test  the	 file  magic  of the input files before	using the read
	      filter.  Only files which	have no	PPM, PGM, PBM  or  FBM	format
	      are  read	 through  the  given filter.  By default all files are
	      read through a given filter.  When no filter  is	specified  the
	      `-t' option has no effect.

ENVIRONMENT
       A  frequently  used  read  filter  can be defined using the environment
       variable	PPM2FLIFILTER.	The name of the	filter can be  preceded	 by  a
       `+' or `-' sign (see the	example	below).	 The `-' sign as first charac-
       ter corresponds to the usage of `-f' in the  command  line  and	a  `+'
       works like `+f'.	 By default `-'	is assumed which means that the	filter
       reads from stdin.

EXAMPLES
   Basic Usage
       Assume the existence of a series	of PPM images which have the names

	    image01.ppm,
	    image02.ppm,
	    image03.ppm,
	    etc.

       The goal	is to produce a	FLI animation from these files	in  the	 given
       order.	 First	 the  list-file	 is  prepared.	 We  choose  the  name
       `pics.list' for this file.  The file is generated by:

	    % ls -1 image??.ppm	> pics.list

       Note that this only works if no other files in the directory match  the
       specified  pattern  and	the desired order corresponds to the numbering
       system in the file names.  In the second	step a FLI file	with the  name
       `anim.fli' is generated using the command:

	    % ppm2fli pics.list	anim.fli

       The  generated  animation  has the resolution 640x480.  Assume that the
       given images are	only 320x240.  Then they appear	in the middle  of  the
       640x480	display	 area  and  are	surrounded by a	border area.  To avoid
       this border we fit the FLI resolution at	the pixel size	of  the	 input
       images.	This can be done by:

	    % ppm2fli -g 320x240 pics.list anim.fli

       In the next example we begin with a series of 768x512 images.  The goal
       is to animate these images, cutting off the top 20 lines	of each	image.
       Again the name of the list-file is `pics.list' and the name of the gen-
       erated FLI file is `anim.fli'.

       The appropriate command line is:

	    % ppm2fli -g 768x492 +oy -20 pics.list anim.fli

       Note 1):
	      492 = 512	- 20.

       Note 2):
	      If in the	given example the `+oy'	option was omitted,  10	 lines
	      at the top and bottom would be cut off.

   Read	Filters
       We  assume that all input images	are in the GIF format and that we have
       the PBMPLUS package with	the program giftoppm installed.	 Like  in  the
       example described above we create a list	file with the names of the GIF
       files.  Then the	FLI is generated by the	command

	    % ppm2fli -fgiftoppm pics.list anim.fli

       In this case all	images given in	`pics.list' have to be in GIF format.

       If we use the FBM package instead of PBMPLUS we	have  to  use  another
       utility.	 Now the command line looks like

	    % ppm2fli -ffbcat pics.list	anim.fli

       The  utility  fbcat converts the	GIF images to FBM format which is read
       by ppm2fli.  Because fbcat understands also  other  formats,  like  SUN
       raster or FBM, the input	files can have different formats.

       It  is  also possible to	use shell scripts as filters.  For instance we
       want to animate a ray-tracer scene.  The	images were generated by  POV-
       Ray but we made a big mess.  Some are stored in QRT format, some	as TGA
       files and others	are already converted to PPM.  To save disk space some
       files  are  compressed  by gzip.	 We are	in luck	because	we used	always
       the correct extensions in the file names.  We have gunzip installed and
       the  utilities  qrttoppm	 and  tgatoppm are available.  We edit a shell
       script with the following content:

	    #! /bin/ksh

	    name=$1
	    cmd=cat

	    function isit
	    {
		 base=${name%.$1}
		 if test "$name" = "$base.$1"; then cmd=$2; fi;
	    }

	    isit "gz" "gunzip"
	    isit "qrt"	   "qrttoppm"
	    isit "qrt.gz"  "(gunzip | qrttoppm)"
	    isit "tga"	   "tgatoppm"
	    isit "tga.gz"  "(gunzip | tgatoppm)"

	    $cmd < $name

       The script is stored as `myfilter' in the current directory (...	 chmod
       a+x myfilter).  To use this filter we type

	    % ppm2fli +fmyfilter pics.list anim.fli

       Note  that  now	`+f'  is required because our filter doesn't read from
       stdin.  It needs	the file name as parameter to choose the corresponding
       utility.	 The given script works	only for the Bourne/Korn shell.

       When the	filter requires	additional parameters they can be passed in an
       easy way.  For instance works

	    % ppm2fli -f "gzip -d" pics.list anim.fli

       for a series of "gzipped" input files.

       Even more complicated things are	possible.  For example the ghostscript
       program	can  be	 used as read filter to	animate	a series of PS images.
       The necessary option may	look like

	 -f "gs	-g320x480 -q -r36 -sDEVICE=ppm -sOutputFile=- -"

       which works for the `tiger.ps' example.	Note that to reduce  the  data
       flow `ppmraw' should be preferred to the	`ppm' device.

       When  a certain filter is often used, the environment variable PPM2FLI-
       FILTER can be set to define the filter.	In a bash environment this may
       look like

	    % export PPM2FLIFILTER=-fbcat

       Then  always  the fbcat utility is used as read filter unless something
       else is defined in the command line.

   Usage of a Map File
       Again we	assume a series	of images, but now the goal is to produce  two
       animations  with	 a different order of the images.  For this purpose we
       edit by hand two	list files `order1.lst'	 and  `order2.lst'.   To  save
       time  and to avoid a repeated scanning of the input images the scanning
       is done in a separate step.  The	result of the scanning is  the	common
       color  table.  This table has to	be stored in an	extra file.  We	choose
       the name	`ct.ppm' for this file.	 Then the first	step looks like:

	    % ppm2fli -w ct.ppm	order1.lst

       In the next step	the first animation is generated:

	    % ppm2fli -m ct.ppm	order1.lst order1.fli

       And finally:

	    % ppm2fli -m ct.ppm	order2.lst order2.fli

       Usually,	if no individual quantization is used,	all  images  are  read
       twice.	Once  for  generating the color	table and the second time when
       the quantize & assembling is done.  Thus, the options `-m' and `-w' can
       help  to	 save  a lot of	time, especially when the input	files are com-
       pressed or have another file format and each reading through  a	filter
       requires	more time.

       Note  that the map file is not read through a given filter.  Thus, this
       file always has to be in	one of the formats which can be	read directly.

   Quantization	using an external utility
       A modified version of the Octree	algorithm is implemented  in  ppm2fli.
       By  default  this  algorithm  is	used when the input files contain more
       than 256	colors.	 This maximum of colors	can be changed to lower	values
       using the option	`-Qc'.	Sometimes it may be desirable to use a differ-
       ent quantization	algorithm.  In the following example we	want  to  ani-
       mate  a	ray-tracer  scene generated by the POV-Ray program.  The image
       files are in gzipped QRT	format and we have the PBM  package  with  the
       utility	qrttoppm installed.  Again the list-file with the names	of the
       QRT images has the name `pics.list'.  The quantization  shall  be  done
       with  the  ppmquant  program  of	the PBM	package, because it offers the
       possibility of Floyd-Steinberg error diffusion.	Nevertheless we	 would
       like  to	 get a FLI animation where the color table is static.  Then we
       do in the first step

	    % ppm2fli pics.list	-w ct.ppm -f"(gunzip | qrttoppm)"

       By that the color table is evaluated by the Octree algorithm and	stored
       in  the	file  `ct.ppm'.	  To  avoid a exceeding	command	line we	edit a
       shell script with the content

	    #! /bin/csh
	    gunzip | qrttoppm |	ppmquant -fs -map ct.ppm

       and store this file as `myquant'	in the current	directory  (...	 chmod
       a+x  myquant).	When  this  is	done  we  generate  the	 FLI animation
       `anim.fli' by the command

	    % ppm2fli pics.list	anim.fli -m ct.ppm -fmyquant

       Note that usually the Floyd-Steinberg  error  diffusion	results	 in  a
       large  number  of isolated pixels in the	quantized image.  This is used
       to avoid	the typical color steps	which occur  in	 regions  with	smooth
       transitions  between different colors.  But the compression method used
       in the FLI format is inefficient	when too many  isolated	 pixels	 occur
       within  an  image.   Thus,  the better image quality is payed by	a much
       larger size of the FLI file.

TECHNICAL NOTES
   The Modified	Octree Algorithm
       The Octree algorithm does the quantization in three phases:

       (1)  Scanning of	the image

       (2)  Reduction of the Octree

       (3)  Mapping

       First the images	are scanned to evaluate	what colors are	present.   For
       this  purpose  internally a list	of colors is created.  To speed	up the
       sorting a tree structure	-- the so called Octree	-- is used rather than
       a  linear  list.	 This tree structure has a main	node which can have up
       to 8 sub-nodes.	Each sub-note itself can have  again  8	 sub-sub-nodes
       and so on.  So the sub-nodes can	be regarded as sub-trees.

       A  geometric interpretation exists for the sorting of RGB colors	by the
       Octree: A RGB color  can	 be  regarded  as  a  point  with  coordinates
       (red,green,blue)	 in  a 3-dimensional space.  The orthogonal coordinate
       system of this space has	axis in	the directions red,  green  and	 blue.
       Total black is defined as the origin of this space (0,0,0).  Because of
       the discrete 8bit  representation  of  each  RGB	 component  the	 point
       (255,255,255) corresponds to maximum bright white.  All possible

	      256*256*256 > 16 Million

       RGB  combinations  form a regular three-dimensional grid	in this	space.
       The grid	can be covered by a cube with side length 255.	This cube cor-
       responds	to the main node of the	Octree.	 The sorting is	done by	subdi-
       viding the cube symmetrically in	8 sub-cubes of equal size.   The  sub-
       cubes contain the points

	      1. (r,g,b) = (  0	- 127,	 0 - 127,   0 -	127)
	      2. (r,g,b) = (  0	- 127,	 0 - 127, 128 -	255)
	      3. (r,g,b) = (  0	- 127, 128 - 255,   0 -	127)
	      4. (r,g,b) = (  0	- 127, 128 - 255, 128 -	255)
	      5. (r,g,b) = (128	- 255,	 0 - 127,   0 -	127)
	      6. (r,g,b) = (128	- 255,	 0 - 127, 128 -	255)
	      7. (r,g,b) = (128	- 255, 128 - 255,   0 -	127)
	      8. (r,g,b) = (128	- 255, 128 - 255, 128 -	255)

       These sub-cubes correspond to sub-nodes of the main node	in the Octree.

       At  the	beginning  all 8 bits of the RGB values	are taken into account
       when sorting the	colors.	 It is checked for a pixel in  which  sub-cube
       its  color belongs.  Then it is checked if a corresponding sub-node for
       this sub-cube already exists.  If not a new node	in the Octree is  gen-
       erated which represents this sub-cube.  Then the	sub-cube itself	is di-
       vided in	eight sub-sub-cubes and	so on.	The subdivision	is done	 until
       the  color is located in	the finest cube	which contains only one	of the
       possible	discrete RGB points.  This results in 8	levels	of  sub-cubes,
       which  all  represent  a	 node  in different levels of the Octree.  The
       nodes in	the finest level (also called deepest level),  which  have  no
       sub-nodes, are called leaves.

       The  sorting procedure is done for all pixels in	the input images.  Ad-
       ditionally the modified algorithm does for each sub-cube	a count	of the
       pixels  which where located in this cube.  Furthermore a	sum of the RGB
       values is computed for all pixels in each sub cube.

       In principle all	pixels in a true  color	 picture  can  have  different
       shades.	Thus, the Octree might grow and	grow, and it may become	impos-
       sible to	store the information for all nodes in the  main  memory.   Of
       course  this  depends  on  the content of the input images.  To avoid a
       very large Octree a reduction is	done, when the number  of  nodes  that
       the Octree has in the second-deepest level exceeds a certain threshold.
       The reduction is	done by	throwing away all leaves in the	deepest	level.
       The  sorting  is	stopped	in the second-deepest level where the nodes of
       the Octree are now leaves.  But,	theoretically 7	levels still allow

	      128*128*128 > 2 Million

       different RGB combinations or possible finest sub-cubes.	 So it can  be
       necessary to reduce the level of	sort accuracy further until the	Octree
       remains small enough.  But this may cause later a poor  result  of  the
       quantization,  because  all  pixels which colors	share a	common leaf of
       the Octree will have the	same color in the resulting  quantized	image.
       Thus, it	is desirable to	keep the accuracy level	a high as possible and
       a compromise between computational effort and quantize quality  has  to
       be obtained.

       In  the	second	phase of the quantization the color table is computed.
       For this	purpose	the Octree which was  generated	 during	 the  scanning
       process	has  to	be reduced further until the number of leaves is lower
       (or equal) than the specified maximum of	colors.	 Compared to  the  re-
       duction	during	the scanning process, which is done only "level-wise",
       the final reduction is performed	in a  more  complicated	 way.	It  is
       taken  into  account how	many pixels belong to each node	in the Octree.
       The node	with the minimum pixel count is	searched.  It's	sub-trees  are
       discarded  and it becomes a leaf.  This is repeated until the number of
       leaves is low enough.  Then for each leaf the average color values  are
       computed: The sums of the red, green and	blue values are	divided	by the
       number of pixels.  These	averaged RGB values are	replaced by the	 near-
       est  integers and the resulting numbers are taken as entry in the color
       table.

       After the color table is	generated the final stage is done.  All	pixels
       in the images are sorted	again using the	-- now reduced -- Octree until
       a leaf is reached.  Then	the pixel is mapped to the respective entry in
       the  color  table.   For	all pixels which were used during the scanning
       process a leaf in the reduced Octree exists.  This  leaf	 represents  a
       cube  in	 the  color space that contains	the color of the pixel (beside
       other colors depending on the level of the leaf).

       In some circumstances it	is useful to be	able to	map also images	 which
       were not	scanned	previously.  If	such an	"unknown" image	is mapped pix-
       els may occur which have	colors that are	not represented	by any leaf in
       the Octree.  These "unknown" colors are located in cubes	which were not
       considered previously.  The sorting process is extended to handle  also
       such  situations.   In all cases	the sorting starts regularly and it is
       evaluated in which sub-cube the color of	a pixel	belongs.   If  a  node
       for  this  sub-cube  exists in the Octree the search is continued regu-
       larly.  If no node exists -- this means no scanned pixel	 had  a	 color
       which  belonged	to the same sub-cube --	an extra procedure is started.
       For all sub-nodes that exist the	distance in  the  3-dimensional	 color
       space between the color of the pixel and	the average color of this sub-
       node is computed	(NOTE: In ppm2fli the maximum norm is used as the dis-
       tance,  not the geometric distance).  Then the search is	continued with
       the sub-node that represents the	lowest distance.  The procedure	is re-
       peated  until a leaf is reached.	 Like in the regular case the pixel is
       mapped to the color of this leaf.  If this extra	 search	 procedure  is
       necessary  for some pixels, ppm2fli counts them and writes in a message
       how many	"non-fitting" pixels were found.

   Controlling the quantization
       In the following	we assume that the maximum number of colors was	deter-
       mined previously	and the	numcolors parameter is kept fix.  Usually this
       value is	256 anyway.  Then the program has two parameters by which  the
       selection  of  the output color table can be controlled.	 These are the
       nodelimit and the reducelevels parameters.  The first one sets the max-
       imum  number of nodes in	the second-finest level.  Like described above
       the level of the	Octree is reduced when during the scanning of the  in-
       put  images this	value is exceeded.  With a deeper level	in the Octree,
       finer nuances between output colors are possible.  This is useful  when
       smooth  transitions  are	present	in the input images.  Typically, steps
       occur in	such transitions due to	the quantization.  These steps may  be
       reduced	when  a	 larger	 nodelimit is used and the final Octree	is one
       level deeper.  The depth	of the Octree can be watched using  the	 `-vv'
       option.	After the scanning of each file	a lines	occurs which look like

	      Octree - node count (5): 1 8 23 66 228 999 0 0 0

       The  number  in	the brackets indicates the deepest level.  Then	follow
       the number of nodes in each level from 0	to 8.  The zero	level contains
       only  the  main	node of	the Octree and the first number	is always one.
       Recommended values of nodelimit are between one time and	four times the
       numcolors  value.   Higher values increase the computational effort and
       slow down the scanning process.

       The reducelevels	parameter controls the final reduction of the  Octree.
       It  determines  the  number  of levels in which the search for the node
       with the	minimum	pixel count is done.  When reducelevels	is  zero,  the
       reduction  is  done only	in the finest level.  Therefore, the resulting
       Octree contains leaves only in two different levels:  the  deepest  and
       the second-deepest.

       The influence of	this parameter on the color table becomes clear	in the
       following example: Assume a 640x480 image which shows a small,  bright-
       red  object in front of a green dominated background.  The small	object
       consists	of only	1000 pixels.  The green	and  blue  components  of  the
       colors  in  this	object are zero.  The red values rage from 150 to 250.
       In the green background the red and blue	values are  zero.   The	 green
       values  rage  from  1  to 255.  For each	of this	green values much more
       than 1000 pixels	can be found in	the image (which has more than 300,000
       pixels).	 Thus, we have a total of

	      101+255=356

       different  colors in the	image.	We assume that the nodelimit parameter
       is larger than 356.  Then the Octree has	a leaf for  each  color	 after
       the  scanning.	Until  now  no	reduction  was necessary.  But now 100
       leaves have to be removed from the Octree.  By default,	the  nodes  in
       all  levels  are	 searched for the node with minimum pixel count.  This
       will be always a	node which represents a	red color,  because  the  1000
       red  pixels  can't stand	the statistical	superiority of the green back-
       ground.	What happens is	that all red pixels are	going to  receive  the
       same  (averaged)	 red  by the quantization and the green	nuances	in the
       background are resolved in an optimal way.

       When the	reduction is limited to	the finest level, the number of	leaves
       that  represent	red colors can only be reduced by a factor of 8.  From
       101 leaves 13 will remain and the same number of	entries	in  the	 color
       table is	occupied by red	shades.	 Thus, the red object doesn't look to-
       tally poor like in the first case.  Now the green background has	to  be
       represented  by	12 entries less.  The preference of shades with	higher
       pixel count is limited with a zero reducelevels value. By default,  the
       nodes  in  all  levels  may  be	turned to leaves, which	results	in the
       strongest preference of dominant	shades in the color table.   Also  the
       statistic  of the reduced Octree	can be watched using the `-vv' option.
       When the	scanning is finished a lines occurs which look like

	      Octree - leaf count (4): 0 4 14 53 184 0 0 0 0

       The number in the brackets indicates the	deepest	leaf level.   This  is
       followed	by the number of leaves	in each	level from 0 to	8.

       In general, the effect of changes of the	above mentioned	parameters de-
       pends strongly on the input data.  To get optimal results, some experi-
       ments with different values should be done.

   FLI/FLC optimization	for special players
       One  special  feature  of  ppm2fli is activated by the `-D' option.  By
       that the	program	generates optimized animations for players  which  use
       double buffering.  A double-buffer player uses two buffers for the dis-
       play.  When playing an animation	both buffers have to be	updated	 sepa-
       rately.	 For  this  a the player needs the update information with re-
       spect to	the frame which	was located previously	in  the	 same  buffer.
       This  frame  is	not  the  last one, which was processed	in exactly the
       other buffer, but the frame before the last.  Ordinary  FLI/FLC	anima-
       tions  contain in each frame the	update information with	respect	to the
       previous	frame.	Thus a double buffer player has	to combine somehow the
       updates	of  two	 FLI frames to make the	changes	in one of the buffers.
       This becomes much easier	when the FLI already contains this information
       in  each	 frame.	  Still	 the  animation	 can  be played	with a regular
       player.	In this	case only some unnecessary updates are done which  may
       slow down the animation.

       A  second  special  feature  is activated by the	`-N' option.  Then the
       frames of the generated FLI animation contain  the  update  information
       with respect to the last	and the	following frame.  This allows the ani-
       mation to be played in reverse direction.  For instance with the	 XAnim
       player  the play	direction can be altered interactively.	 This may help
       when visualizing	and analyzing some unsteady phenomena or just  can  be
       used  as	a fancy	effect.	 Together with the utility unflick an existing
       FLI animation can easily	be converted to	be suitable for	reverse	play.

SEE ALSO
       fbm(1), unflick(1), and ppm(5)

REFERENCES
       The quantization	is based on the	Octree algorithm introduced by Michael
       Gervautz	and Werner Purgathofer (Technical University Vienna, Austria).
       It is described in the article `A Simple	Method for Color Quantization:
       Octree  Quantization' published in Graphic Gems edited by Andrew	Glass-
       ner pp. 287 ff.

ACKNOWLEDGMENTS
       The special feature, to generated FLI animations	which  can  be	played
       forward	and  backward,	is  based  on  contributions and ideas of Marc
       Podlipec	(podlipec@wellfleet.com).  This	 manual	 page  includes	 parts
       form  that  one	of  fbm2fli  which  was	 assembled by R. P. C. Rodgers
       (rodgers@nlm.nih.gov).

AUTHOR
       Klaus Ehrenfried	(klaus.ehrenfried@tu-berlin.de).  Release  of  January
       2002.

       http://vento.pi.tu-berlin.de/fli.html

				11 January 2002			    PPM2FLI(1)

NAME | SYNOPSIS | DESCRIPTION | QUANTIZE OPTIONS | FLI/FLC OPTIONS | GENERAL OPTIONS | ENVIRONMENT | EXAMPLES | TECHNICAL NOTES | SEE ALSO | REFERENCES | ACKNOWLEDGMENTS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ppm2fli&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help