============================================================================
  mh_PLAYer  -  COLOUR THEME  (plugin add-on)
  Plugin v1.0   |   targets mh_PLAYer v2.12.1+   |   2026-06-26
============================================================================

A drop-in plugin for mh_PLAYer that renders a whole shot, sequence or feature
as a single image - the "movie barcode". Every sampled frame becomes one
vertical stripe, so the colour story of the piece reads left to right.

Studios, editors and colourists use these for look development, colour
scripts, grading references, presentation boards and poster art.

Two stripe styles, matching the two looks these are usually made in:

  SQUEEZE   Each frame is squashed into a thin column, keeping its vertical
            structure - sky at the top, ground at the bottom. This gives the
            soft, streaky look.

  AVERAGE   Each frame collapses to a single flat colour column, giving the
            hard-edged classic barcode.

SHIPPED WITH mh_PLAYer v2.12.2 AND NEWER. This plugin is already in the
plugins folder next to the mh_PLAYer .exe - there is nothing to install.
The standalone download below is for adding it to v2.12.1, or for picking
up a newer or corrected copy between mh_PLAYer releases:
  https://anti-matter-3d.com/mhplayer/


CONTENTS OF THIS ARCHIVE
----------------------------------------------------------------------------
  colour_theme.py   The plugin
  README.txt        This file


REQUIREMENTS
----------------------------------------------------------------------------
  mh_PLAYer        v2.12.1 or newer
  Licence tier     Plugin Scripting (Studio Pro). The Plugins menu is
                   locked on lower tiers.
  Platform         Windows (as per mh_PLAYer)

  No extra Python install is needed - the plugin runs inside mh_PLAYer and
  uses the Pillow / NumPy / OpenCV that already ship with it.


INSTALL  (only if you are NOT on v2.12.2 or newer)
----------------------------------------------------------------------------
  On v2.12.2+ this plugin is already installed - skip to USING IT.

  1. In mh_PLAYer:  Plugins menu  ->  "Open Plugins Folder..."
     (this is the folder next to the mh_PLAYer .exe - the only location the
      player scans)
  2. Copy  colour_theme.py  into that folder.
  3. Plugins menu  ->  "Reload Plugins"   (or restart mh_PLAYer)
  4. Run it:  Plugins menu  ->  "Colour Theme..."

  To remove it, delete colour_theme.py from the plugins folder and restart.


USING IT
----------------------------------------------------------------------------
  SOURCE
    Folder...   an image-sequence folder
    Files...    individually picked images
    Video...    a video file - a single shot, or a whole feature
    If a clip is already loaded in the player, the source is pre-filled.

  STRIPE STYLE
    Squeeze     keeps each frame's vertical structure (soft, streaky)
    Average     one flat colour per frame (hard-edged barcode)

  GEOMETRY
    Stripes (columns)   How many frames are sampled across the whole source.
                        More stripes means finer detail. 1200 is a good
                        starting point for a feature; 200-400 suits a shot.
    Stripe width (px)   Width of each stripe. 1-3 px gives the classic dense
                        look; wider stripes suit short sequences.
    Height (px)         Height of the barcode band.
    Smooth              Softens stripe edges. Best left off for the Average
                        style, and used sparingly with wide stripes (see the
                        note under KNOWN BEHAVIOUR).

    The dialog shows the resulting barcode size as you change these, and
    warns when it becomes very wide.

  HEADER & OUTPUT
    Add a header        Title above the barcode, as seen on published film
                        barcodes.
    Average-colour bar  A solid block of the overall average colour of the
                        whole piece, beside the title.
    Title               Defaults to the source name if left blank.
    Background          Black or white.
    PNG file            Browse to set the path. If left blank, the image is
                        written next to the source as
                        <source>_colour_theme.png

  Save Settings stores your choices so they are remembered next time.


SPEED ON LONG SOURCES
----------------------------------------------------------------------------
  Video frames are skipped without decoding, and only the sampled frames are
  decoded, so a feature-length file does not have to be fully decoded. It is
  still a single linear pass through the file, so a long feature will take a
  while. The progress dialog can be cancelled at any point.

  Raising the stripe count costs very little extra time - the pass through
  the file dominates - so if you are processing a feature anyway, a higher
  stripe count is usually worth it.


KNOWN BEHAVIOUR
----------------------------------------------------------------------------
  - Smoothing is a normal blur, so it softens vertically as well as
    horizontally. At 1-3 px stripe widths this reads fine; with wide stripes
    it will also blur the vertical structure of the Squeeze style.

  - Stripes are built from the DECODED image, not from mh_PLAYer's colour
    managed display. For scene-linear EXR material the values are not display
    referred. Treat the result as a look reference, not as a grading
    measurement.

  - If a source has fewer frames than the requested stripe count, every frame
    is used and the barcode simply has fewer stripes.


SUPPORTED INPUT
----------------------------------------------------------------------------
  Images   .png  .tif  .tiff  .jpg  .jpeg  .bmp  .webp
  Video    .mp4  .mov  .mkv  .avi  .webm  .m4v  .wmv  .mxf

  EXR sequences are not supported in this version.


SETTINGS
----------------------------------------------------------------------------
  Your settings are remembered automatically between sessions - use
  "Save Settings" in the dialog to store the current choices.

  "Reset to Defaults" restores every field to its factory value.
  Nothing is written until you click Save Settings, so you can reset,
  look, and close without committing the change.


TIPS
----------------------------------------------------------------------------
  - For a print or poster, use the Squeeze style with 1 px stripes and a tall
    height, then scale the result to the size you need.
  - For a quick read of an edit's colour progression, Average with 2-3 px
    stripes makes each shot clearly visible as a block.
  - White background with a black title suits documents and slides; black
    suits screens and presentation boards.
  - Running the same source in both styles and stacking them makes a strong
    look-development page.
  - Turn the header off to get a clean band you can lay out yourself.


LICENCE & SUPPORT
----------------------------------------------------------------------------
  (C) 2026 Martin P. Heigan - anti-matter-3d.com

  This plugin is provided for use with a licensed copy of mh_PLAYer and is
  covered by the mh_PLAYer licence terms.

  Questions / feedback / more tools:
    https://anti-matter-3d.com/contact/
    https://anti-matter-3d.com/
============================================================================
