pxart palette

palette FILE [--add k=#hex ...] [--variant NAME [--add k=#hex ...] [--keep KEYS]] [--variant NAME --derive-from base|VARIANT [--match FILE%V] [--darken F] [--tint COLOR] [--keep-lit KEYS] [--lift-darks]] [--comment KEY|@variant NAME 'text' [KEY 'text' ...]] [--comment-header 'text'] [--hoist KEYS] [--export out.gpl|out.hex [--used]] [--extract-to P.px [--repoint]] [--remove KEYS [--to KEY]] [--in DIR] [--import P.px] [--order KEYS] [-o OUT] [--dry-run]

usage: pxart palette FILE [OPTIONS of one mode; the modes are below]

  palette FILE [--add k=#hex ...] [--variant NAME [--add k=#hex ...] [--keep KEYS]]
          [--variant NAME --derive-from base|VARIANT [--match FILE%V] [--darken F] [--tint COLOR]
           [--keep-lit KEYS] [--lift-darks]]
          [--comment KEY|@variant NAME 'text' [KEY 'text' ...]] [--comment-header 'text']
          [--hoist KEYS] [--export out.gpl|out.hex [--used]] [--extract-to P.px [--repoint]]
          [--remove KEYS [--to KEY]] [--in DIR] [--import P.px] [--order KEYS] [-o OUT] [--dry-run]
      List a file's palette and what each variant does; or edit it: add keys and variants, derive a
      night or dusk, hoist, import, remove, order, comment, export.

positional arguments:
  file

options:
  -h, --help                         show this help message and exit

list (no edit options):
  Print the palette, where each key comes from and how often it's drawn, and what each variant recolors.

  --in DIR                           for a palette file: how many .px files under DIR import it, and draw with each key

add / remove / order base keys:
  Edit FILE's own palette lines.

  --add k=#rrggbb [k=#rrggbb ...]    add keys (with --variant: set them in that variant)
  --remove KEYS                      take these keys out of FILE (with their variant lines)
  --to KEY                           with --remove: repaint the removed keys' pixels as KEY first
  --order KEYS                       put these keys first in FILE's palette, in this order

variants:
  Set or inherit keys in one variant, by hand: --variant NAME --add k=#hex.

  --variant NAME                     --add, --keep and --derive-from edit this variant (made if FILE has none)
  --keep KEYS                        with --variant: these keys inherit the base colors in it

derive:
  Build a whole variant from the base or another variant: --variant NAME --derive-from base.

  --derive-from base|VARIANT         with --variant NAME: set every key in NAME from its color here, --darken'ed and --tint'ed
  --match FILE[%VARIANT]             with --derive-from: first map each channel as FILE's base->VARIANT does (a fitted gain and offset)
  --darken F                         with --derive-from: each channel times 1 - F (0..1)
  --tint COLOR                       with --derive-from: '#rrggbbaa' laid over each color, as scene's
  --keep-lit KEYS                    with --derive-from: these keys keep their color (lamps)
  --lift-darks                       with --derive-from: let the derive brighten keys darker than a quarter (else never)

import / hoist:
  Share one palette file between sprites.

  --import P.px                      add '@palette P.px' to FILE, dropping FILE's key lines P has in the same colors
  --hoist KEYS                       move these keys into the palette file FILE imports
  --extract-to P.px                  write FILE's palette and variants as a palette file
  --repoint                          with --extract-to: FILE then imports it

comments:
  The comment lines above key and @variant lines, and FILE's header.

  --comment KEY TEXT [KEY TEXT ...]  KEY 'text' or @variant NAME 'text', one or more in turn (--comment y 'lamp' E 'flame'): the comment line above that line ('' removes it)
  --comment-header TEXT              the comment at the top of FILE ('' removes it)

export:
  Write the palette for another tool.

  --export OUT.gpl|OUT.hex           write the base palette as a GIMP .gpl or a .hex list
  --used                             with --export: only the keys FILE's frames draw with

where an edit goes:
  With any edit above (not the listing or --export).

  -o OUT                             write the edited FILE to OUT (its @palette lines re-pointed from there); FILE stays as it is
  --dry-run                          print what the edit says and a diff of each file it would change; write nothing

      Rules ('pxart help palette-rules' prints only these):
        - No flags lists the palette: each key, its color, where it comes from and how often
          it's drawn, then what each variant recolors.
        - Edits write FILE's own lines (-o OUT: a copy; --dry-run: a diff, nothing written). An
          imported key or variant is edited in its palette file: --hoist moves FILE's keys
          there, and --remove of an imported key takes it out there when no other sprite under
          the directory uses it.
        - A variant is key lines over the base: --variant NAME --add sets keys in it (a key in
          its base color stays lit), --keep lets keys inherit, and --derive-from builds a
          whole variant from the base (--match fits another palette's mood; keys darker than a
          quarter are held dark).
        - Only a variant's edits (--variant with --add, --keep or --derive-from) and --remove
          --to change how FILE renders. --add of base keys, --import, --hoist, --extract-to
          --repoint, --order, --comment and --remove of undrawn keys keep every pixel, in
          every variant.
        - Sharing one palette file: --extract-to P.px [--repoint] writes it from FILE,
          --import P.px points FILE at one, and --in DIR says which sprites under DIR import
          it.
      Examples: 'palette party.px' lists it; 'palette pal.px --variant night --add k=#120e22
      w=#9fb0d4'; 'palette pal.px --variant dusk --derive-from base --match mossback.px%dusk'.

      Listing: after the keys (rule 1), each variant's line: 'dusk: recolors (darker) o x X
      c C; inherits: e E q' (the keys it recolors, then the base keys it leaves alone, both
      in palette order). A recolor is darker, brighter ('brightens y W': lamps lit brighter
      at night) or as bright (Rec. 709 luma, times alpha). A key the variant lists in its
      base color (a lamp that stays lit at night) is neither: 'night: recolors (darker) k w;
      relists unchanged: l g; inherits: nothing'. The palette's comments come along: the
      palette files' header on top, a key's comment after its line ('E #ffe07a local #
      light-emitting keys'), each variant's comment under its line, and the comments on its
      key lines as 'y: # lit in rain: harbor lamp'. A palette file has no 'used' column; --in
      DIR counts the .px files under DIR that import it ('imported by 3 of the .px files under
      crossover/') and, per key, how many of them draw with it ('used by 2 files').

      Base keys: --add k=#hex (or a palette line as the file has it, 'k #hex') adds them.

      Authoring a variant: with --variant NAME, --add sets the keys in that variant instead,
      over what it had, and makes the variant when FILE has none by that name (the example
      above). --variant NAME --keep l,g lets keys inherit the
      base colors: their lines in the variant go, and a key an imported variant recolors gets
      its base color on a line of FILE's own, since the import can't change from here. --add
      and --keep can share one call; the keys must be in the base palette. A key --add gives
      the color it already has is left, and said so: 'k is already #0f0f22 in night;
      unchanged'.

      Deriving a variant: --variant night --derive-from base --darken 0.35 --tint '#10183060'
      --keep-lit y,W sets every key of FILE's palette (imported ones too, unless FILE imports
      a night) in night from its base color (or from another variant's: --derive-from
      dusk), each channel times 1 - F (--darken 0.35 keeps 65%), then the --tint color laid
      over at its alpha, the math of scene --tint; the --keep-lit keys keep their
      --derive-from color, listed as lamps kept lit. A key that comes out in its base color
      gets no line. --add in the same call then sets single keys over the derived ones.

      --match FILE%dusk (or FILE:dusk; FILE alone means the variant being made) first maps
      each channel the way FILE's own base -> dusk does, a gain and an offset per channel
      fitted by least squares over the keys that variant recolors (not the ones it relists,
      the lamps), then --darken and --tint as above: the example above gives the cast
      another pack's dusk (a red gain, a blue offset), where one darken and one tint move
      every channel alike. The output prints the fit: 'r x0.92 -17, g x0.81 -11, b x0.78
      +10'. The hold: a key darker than a quarter (Rec. 709 luma, .2126 R + .7152 G + .0722
      B of the sRGB values, under 64) never comes out with a higher luma than its
      --derive-from color: it is scaled back to that luma, its hue kept (a warmer red may
      look a shade lighter), and listed as held, so a near-black outline stays dark under a
      blue tint or offset; else 'held: none'.
      --lift-darks lets the derive brighten them (a fog), and names the ones it did; --add
      sets one anyway.

      Comments: --comment KEY 'text' sets the comment right above FILE's line for KEY
      (replacing the comment lines there; blank lines stay); --comment @variant night 'text'
      the one above '@variant night', which --extract-to and compose carry as the variant's
      section note; with --variant NAME, --comment KEY is KEY's line in that variant. A line
      of FILE's own: an imported key or variant is commented in its palette file.
      --comment-header 'text' sets the comment at the top of FILE. '' removes a comment; a
      newline in the text makes two comment lines. One --comment takes several in turn
      ('palette pal.px --comment y "lamp" E "flame"'), and both repeat and go with --add in
      one call (the key added first): 'palette pal.px --variant night --add k=#120e22
      --comment @variant night "night: only lamps glow"'.

      Removing keys: --remove k,n takes FILE's own keys out: their key lines, their lines in
      FILE's variants, and the comments above those. A key a frame still draws with is
      E_SELECT (naming the frames and how many px), unless --to j repaints those pixels as j
      first: 'palette party.px --remove k,n --to j'. An imported key is repainted the same way
      in FILE, then removed from the palette file that defines it only when no other .px under
      DIR uses it (draws with it, or lists it in a variant, with no key line of its own); DIR
      is --in DIR, else the directory holding both FILE and the palette file. Otherwise it
      stays there, and a line names who uses it: 'b stays in pal.px: cavegirl.px uses it'.
      A palette file's own --remove can't see the sprites that import it: check them after
      (palette pal.px --in DIR shows who draws with each key).

      Order: --order o,t,k (or otk) moves FILE's own key lines to the top of its palette in
      that order, each with the comment and blank lines above it, the other keys after them as
      they were: group a material's ramp, or put the outline first. Variants and a
      '. transparent' line keep their places.

      Sharing a palette file: --import P.px adds '@palette P.px' to FILE (re-pointed from
      FILE's directory) and drops FILE's key lines P has in the same colors (and their variant
      lines P's variants say already), saying which: 'dropped o t k (their key lines: the same
      colors in pal.px)'. A key FILE has in another color than P's is E_KEY_CONFLICT, with
      free keys for FILE's and the recolor that moves them ('pxart recolor boy.px 'k>a''),
      then --import again. FILE renders as before, in every variant it had: where P's variant
      of that name would recolor a key FILE keeps, FILE's variant lists the key's color, and
      says so. A variant only P has comes along (a note says so).

      --hoist l,g moves FILE's own keys into the palette file it imports (its one @palette),
      with their lines in FILE's variants and the comments above both, so every sprite that
      imports it gets them; FILE renders as before. A key the palette file has in another
      color is E_KEY_CONFLICT (give FILE's a free key first: recolor FILE 'l>L'); a variant
      line the palette file has in another color stays in FILE.

      --extract-to P.px writes FILE's whole palette as a palette file for @palette: every key
      FILE renders with (imported ones too, local ones winning) and every variant, with the
      comments that document them: those above key and @variant lines (a section comment, '#
      glow: left out of dusk on purpose'), from FILE and the palette files it imports, and a
      palette file's header comment (a sprite's header is about the sprite and stays).
      --repoint then replaces FILE's @palette, key and @variant lines with '@palette P.px'
      (re-pointed from FILE's directory): FILE renders the same, and other sprites can share
      P.px.

See also, in pxart help all: FORMAT: variants (@variant, %VARIANT); FORMAT: paths (what a
  path is read from: the current directory, or a file's own); EDITING (-o OUT gets the whole
  file, only changed lines are rewritten, 'no change'); FORMAT: selecting frames (FILE:SEL,
  an unnamed grid's name, zsh's "${F}:sel").

pxart help all has the whole reference, pxart help TOPIC one part of it.

This is the output of pxart help palette. The other editing commands and their shared notes are in pxart help EDITING.