MNGVideo addition to Swarm
  by R. Stephan, 2001
==========================

General description
-------------------
This version transforms a series of model states, taken from the cartesian
grids of your model, into a losslessly compressed MNG stream.  A vanilla
PNG stream is built where magnification, as in ZoomRaster, does not 
increase file size.

To view the videos one could use the Mozilla[*] or Konqueror[*] browsers, 
or one of the viewers from the contrib directory of the libmng package[*].  
No additional code is needed for creation as Swarm already presupposes the 
existence of libpng.  The PNG/MNG file formats are patent-free.

[*]
http://www.libmng.com
http://www.mozilla.org
http://www.konqueror.org
http://www.libpng.org/pub/png/libpng.html

What's in the package
---------------------
All files in this package distributed under GPL2.  It consists of:

- Obj-C classes:  MNGVideo.{m,h}

So these files are all you need if you want to use this package.
You can also build libMNGVideo.a once, and make install it, then
put it into your model Makefile APPLIBS variable.
The rest of the included source is for testing.

- Obj-C test application code, to be exact:
  - NaSch-single (of trafficdemo fame, for testing 1-bit block videos),
  - aquarium (a silly model),
  - heatbugs from swarmapps-2.1.1

In the following, parts of this package are discussed in detail.


MNGVideo
--------
This is a class for writing a single MNG video.
In v.0.1, only 1-bit depth (black-white) was supported.
This is now (v.0.3) a special case which you get if you use only
the object layer and one color plus background. 

Ideally, one would create the MNGVideo object by using one
of its constructors after Grid creation in the buildObjects
message of your ObserverSwarm, then set the layers (Value and/or Object), 
and not forget to schedule the takeAFrame message of MNGVideo later.

Messages
--------
+create: aZone ColorMap: <Colormap> cm MagFactor: (unsigned) m;

  The behaviour of this is to create a video object with the given 
  magnification, and set default framerate (10 fps), number of frames (100), 
  and file basename ("swarm" -> "swarm.mng").  

+create: aZone 
   ColorMap: <Colormap> cm 
   MagFactor: (unsigned) m 
   FrameRate: (unsigned) rate NFrames: (int) nf
   NFrames: (int) nf 
   Basename: (const char*) name;

  This is like above plus you can set fps, n_frames, and basename.

+createBegin: aZone;
-createEnd;
-setWidth: (int) w;
-setHeight: (int) h;
-setColormap: <Colormap> cm;
-setMagnification: (int) mag;
-setFrameRate: (int) fps;
-setNFrames: (int) nf;
-setBaseName: (char*) filebase;

  The most flexibility you have with using createBegin/createEnd and
  setter functions. You will get error messages on stderr if values are wrong.
  Values of 0 for width or height set it from the grids, bigger values
  are clipped.

  Now, once you have the video object, you set its layer/s.  These
  correspond to the *2dDisplay classes you already use with your model.

-(void)setValueLayerGrid: <Discrete2d> d MappingM: (int)m C: (int)c;
-(void)setObjectLayerGrid: <Discrete2d> d ObjectCollection: c Message: sel;

  A MNGVideo holds at least one layer which can be set using
  the above messages.  Objects are opaque against a possible value layer.
  If the values in your Value2dDisplay directly correspond to color numbers
  in the Colormap, you can set the mapping factor m to 0 (or 1); c is the
  offset of value colors within the palette.  When setting a mapping factor,
  through which values are divided before adding the offset, be sure to know
  your biggest possible value that can occur.
  Setting the object collection to nil assumes that if a grid cell is non-nil,
  it contains an object that accepts the given message.  If the message is
  also nil, and there is no value grid, we fall back to white on black.


The class does not make a screenshot!  So this is different from
other approaches --- it's perfectly possible to build MNG videos
from screenshots, too, for example with a MNG editor.  You might
want to take that approach if your agents draw themselves using 
the draw: pixmap message - the library draws background in this case. 

What's missing is a GUI widget to manually start/stop the video, 
conditionally compiled in dependent on the existence of a macro.


Test apps
---------
This has to be tested manually.  It should produce MNG file(s) in
the main directory:

              spec.       nbits   size
             -------------------------
 heatbugs    vgrid+ogrid    8   231267 
 trafficdemo    b/w         1    69070
 aquarium    2 col. ogrid   2    57966


ralf@ark.in-berlin.de

$Id: README,v 1.13 2001/04/14 12:28:17 ralf Exp $

