=======================
DiffKey (version 0.4)

Screen shots and example video clips:
http://diffkey.sourceforge.net/

Downloads and CVS:
http://sourceforge.net/projects/diffkey/

DiffKey is something I've been wanting to write for a year or two, but didn't
get around to it until several weeks ago.  It still has some rough edges, but I
think it's functional enough to be useful.  The only keying plugin included
with Cinelerra (the most prominent non-linear video editor for Linux) is a
Chroma Key plugin with a very cumbersome interface (one slider with a color bar
above it chooses the color for keying).  The results of tinkering with the
settings on that plugin for quite a long time were marginal at best.  This
plugin, therefore, was designed to fill my need for a bluescreen compositor
good enough for heavy-duty use in a Star Wars fan-film.  One of my goals for
this project is to help make Linux a more viable option for the fan-film
community.


------------------
Current features


- Allows the user to capture a "key" frame, which is pure background with no
  subject onscreen
- Allows the user to generate an alpha-transparency mask based on differences
  in Hue, Saturation, Value, Red, Green, and Blue, between the current frame
  and the "key" frame, on a pixel-by-pixel basis
- Allows viewing of the mask only (black=transparent, white=opaque,
  gray=transitional)
- Adjustable visibility threshold to help fill in semi-transparent areas that
  should be opaque
- Adjustable transparency threshold to help make random background noise
  transparent
- Adjustable desaturation threshold to cancel out background color when motion
  blur makes it show through

------------------
Planned features


  Many - see the file "TODO"


------------
Known bugs


- I think render farm and SMP support might be broken, but I don't have the
  means to test it right now


--------------
Requirements


* Cinelerra (the included binary was build for 1.1.8)
* The Cinelerra source code (if you wish to recompile the plugin)
    http://heroinewarrior.com/cinelerra.php3


--------------
Installation


See the file "INSTALL"


------------------
Using the plugin

The first step in building a composite with DiffKey is the acquirement of a key
frame.  This frame must contain the background against which your subject has
been filmed.  The key frame mustn't contain any objects which subsequently
move, because such movements would cause the bluescreen/background to appear
where the object used to be.  When you instantiate the DiffKey plugin, the
first frame that it receives automatically becomes the key frame.  You can
select a different frame as your key frame by navigating to it and pressing the
"Reset key frame" button.  At this point, the track (or black void) behind your
foreground track should show through completely.

Once you have done this, move to a frame which contains your subject.  You may
see your subject showing up already, depending on the default settings which
were loaded with the plugin.  Now is the time to start adjusting the
sensitivity of the mask generated by DiffKey.

I'd strongly advise starting with everything turned off (uncheck all the check
marks).  Next, turn on one of the sensitivity settings, and set it to a value
which works well for your material.  One way to do this is to turn on
"Show Mask" and then bring up the sensitivity slider to the point just before
you start seeing faint background noise all over the screen.  When you are
satisfied with this particular sensitivity setting, turn it off and do the same
thing for the next one.

After you've set all of the sensitivity levels, turn them all on, and also
enable and adjust "Visibility Threshold".  This setting can sometimes be
helpful for filling in unfilled areas in your subject.  The trade-off is that
it also increases the level of background noise, which can lead to blue
speckles all over your video footage (assuming you filmed against a
bluescreen).

The next thing to do is to reduce background noise by turning on and adjusting
the "Transparency Threshold".  The danger here is that semi-transparent areas
of your subject may become completely transparent if you are not careful.

Finally, try to find a frame of video which contains quick movement.  Your
background color may show up in these frames.  If you filmed against a
bluescreen, this will mean ugly blue halos following behind the movement.  You
can reduce this effect by using the "Desaturation threshold".  This will remove
the background color from the semi-transparent images.  If you set this too
high, you'll turn the blue halo into a black halo.  With conservative settings,
however, desaturation can be quite helpful.

Having come this far, you should be at a pretty good starting place.  Now is
the time to move to other frames of footage and tweak the settings.  Look for
frames that are particularly problematic, and drop labels on them so you can
switch amongst them quickly while trying different settings.  You might also
find that your results improve when using a different key frame.  This is
especially true when using cheap cameras (like mine) which don't allow you to
turn off certain automatic color-correction features.  Be sure to keep track of
exactly which frame you are using for your key frame, as you will need this
information before you're finished.

In a perfect world, DiffKey would generate flawless masks, and this README
would be finished now.  The truth is, however, there are always some
irregularities which just don't look right.  For this reason, I've made it my
practice to run the output of DiffKey into the "Blur" plugin.  Turn off
blurring of the Red, Green, and Blue channels, so that only the Alpha channel
is affected.  Set the radius as conservatively as possible.  Settings of 2-5
seem subtle enough to look natural, but strong enough to smooth out most
small imperfections.

When you are finally satisfied with the results your are getting, there is
still one more step you need to take.  When you "Render..." in Cinelerra, a new
and separate copy of DiffKey is created.  This new DiffKey will have the same
settings, but will not have your key frame.  For this reason, the first frame
in the timeline will be the first frame that DiffKey sees when rendering, and
will therefore before your key frame.  As a consequence, the last step in the
DiffKey compositing process is to edit your clip so that the first frame is the
one you want to use for your key.  Sorry about this additional complication,
but there's nothing I can do about it until I address some other design
questions.

Thanks for trying the plugin, I'd welcome any feedback you feel like providing.

|)
|)enji

Benjamin Flaming
diffkey@solobanjo.com
