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

A drop-in plugin for mh_PLAYer that extracts the dominant colours from your
material and renders them as labelled swatch blocks - hex, RGB and coverage
percentage. Useful for colour scripts, look references, grading notes, mood
boards and client presentations.

Three ways to build a palette sheet:

  1. IMAGES                - one image, a folder of frames, or picked files
  2. VIDEO, SCAN FOR CUTS  - a palette per detected shot, giving you a colour
                             script of the whole edit
  3. VIDEO, EVEN INTERVALS - palettes sampled across the clip, either a fixed
                             count or one every X seconds

Output is a palette sheet PNG, with an optional swatch list exported as
TXT, JSON or CSS.

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

  To remove it, delete colour_palette.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)
    A single image file typed or pasted into the source box also works.
    If a clip is already loaded in the player, the source is pre-filled.

  PALETTE
    Colours per palette   2-24 swatches. If an image contains fewer distinct
                          colours than you ask for, the extra swatches are
                          merged away rather than repeated.
    Order by              Coverage (most dominant first), Luminance (dark to
                          light), or Hue (around the colour wheel).
    Analysis size (px)    Longest edge the image is reduced to before
                          clustering. Larger is more accurate but slower;
                          200 px is a good balance.
    Combined palette      Adds a final master palette clustered across every
                          source on the sheet.

  VIDEO SAMPLING  (only the fields for the chosen mode are active)
    Cut sensitivity       1-100. Higher finds more cuts. Start at 45.
    Min shot length       Ignores cuts closer together than this many frames,
                          suppressing false hits from fast motion and flash
                          frames.
    Interval by           "Total count" spreads N palettes across the clip;
                          "Every X seconds" samples on a time step.
    Max palettes          Safety cap so a long clip cannot produce a runaway
                          sheet.

  SHEET & OUTPUT
    Swatch size           Width and height of each colour block, in pixels.
    Thumbnail beside      Shows the source frame at the start of each row.
    Show values           Prints hex, RGB and coverage % under each swatch.
    Sheet title           Defaults to the source name if left blank.
    PNG file              Browse to set the path. If left blank, the sheet is
                          written next to the source as  <source>_palette.png
    Swatch list           Optional TXT / JSON / CSS export, written alongside
                          the PNG with the same name.

  PREVIEW
    Shows the palette of the first source image, updating as you change the
    colour count or ordering. "Refresh Preview" re-reads the source. Use it
    to dial in the settings before processing a whole clip.

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


HOW THE COLOURS ARE FOUND
----------------------------------------------------------------------------
  Pixels are downsampled and grouped by k-means clustering, which finds
  perceptually dominant colours rather than merely the most frequent exact
  pixel values. The percentage under each swatch is that colour's share of
  the analysed pixels.

  Two things worth knowing:

  - The COMBINED palette is a fresh clustering across all sources, not a
    pick of the per-row colours. With a low colour count across very
    different shots it can produce blended colours that do not appear in any
    single frame. Raise the colour count for a more literal result.

  - Palettes are taken 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 sheet as a look reference, not as a grading
    measurement.


ABOUT CUT DETECTION
----------------------------------------------------------------------------
  Cuts are found by comparing each frame with the previous one. This detects
  HARD CUTS reliably. It does NOT reliably detect dissolves, cross-fades,
  fades to or from black, or very fast camera moves (which may register as a
  cut).

  For material with many dissolves, use the even-interval mode instead.

  Scanning 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 colour script of an edit, use "scan for cuts" with 5 or 6 colours
    per palette and the combined palette switched on.
  - Order by Hue for a mood board, by Coverage for grading notes.
  - Six colours suits most live-action frames; graphic or animated material
    often reads better with three or four.
  - The CSS export drops straight into a web project; JSON is the one to use
    if you want to drive another tool from the results.
  - Turn thumbnails off for a compact, printable colour-only sheet.


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