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

A drop-in plugin for mh_PLAYer that builds a labelled thumbnail grid - a
contact sheet - from a set of frames or from a video. Useful for shot
breakdowns, dailies overviews, reference boards and client hand-outs.

Three ways to fill a sheet:

  1. IMAGES              - a folder of frames, or individually picked files
  2. VIDEO, SCAN FOR CUTS - detects hard cuts and grabs the first frame of
                            each shot, giving you a shot breakdown
  3. VIDEO, EVEN INTERVALS - N thumbnails spread across the clip, or one
                            every X seconds

Each thumbnail is labelled with its filename plus frame number and timecode.
Output is a PNG, with an optional multi-page PDF for long clips.

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
----------------------------------------------------------------------------
  contact_sheet.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  contact_sheet.py  into that folder.
  3. Plugins menu  ->  "Reload Plugins"   (or restart mh_PLAYer)
  4. Run it:  Plugins menu  ->  "Contact Sheet..."

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


USING IT
----------------------------------------------------------------------------
  SOURCE
    Choose one of the three modes, then point it at your source:
      Folder...  a folder of images          (Images mode)
      Files...   pick individual images      (Images mode)
      Video...   pick a video file           (either video mode)
    If a clip is already loaded in the player, the source is pre-filled.

  SAMPLING  (only the fields for the chosen mode are active)
    Cut sensitivity        1-100. Higher finds more cuts. Start at 45 and
                           adjust: too many thumbnails means lower it, missed
                           cuts means raise it.
    Min shot length        Ignores cuts closer together than this many frames.
                           Suppresses false hits from fast motion, flash
                           frames and strobing.
    Interval by            "Total count" spreads N thumbnails evenly across
                           the clip; "Every X seconds" samples on a time step.
    Max thumbnails         Safety cap (default 200) so a too-sensitive scan
                           cannot produce a runaway sheet.

  SHEET LAYOUT
    Columns, thumbnail width, gap and margin control the grid. Thumbnail
    height follows the source aspect automatically. "Label each thumbnail"
    prints the filename plus frame number and timecode under each cell.
    Sheet title defaults to the source name if left blank.

  OUTPUT
    PNG file        Browse to set the path. If left blank, the sheet is
                    written next to the source as  <source>_contact_sheet.png
    Multi-page PDF  Optional. Splits the thumbnails across pages using the
                    "Rows per PDF page" value. The PDF is written alongside
                    the PNG with the same name.

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


ABOUT CUT DETECTION
----------------------------------------------------------------------------
  Cuts are found by comparing each frame with the previous one (frame
  differencing on downscaled greyscale frames). This detects HARD CUTS
  reliably.

  It does NOT reliably detect:
    - dissolves and cross-fades
    - fades to / from black
    - whip pans and very fast camera moves (may register as a cut)

  For material with a lot of dissolves, use the even-interval mode instead,
  or lower the sensitivity and accept a rougher breakdown.

  Scanning for cuts decodes every frame, so a long clip takes time. The
  progress dialog can be cancelled at any point - a cancelled scan still
  builds a sheet from the shots found so far.


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.

  Timecode is non-drop (HH:MM:SS:FF), calculated from the source frame rate.


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 quick shot breakdown of an edit, use "scan for cuts" with 5 or 6
    columns and a 420 px thumbnail width.
  - For a single long take, "every X seconds" gives a more even overview than
    cut detection.
  - Very wide sheets are easier to read as a PDF than as one tall PNG - tick
    the PDF option and set rows per page to suit your paper size.
  - Turning labels off gives a clean image grid for reference boards.


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/
============================================================================
