mdpicgen

Helps keep Markdown editing fun.

This tool reads string sequences from Markdown and generates custom visuals using custom image layers. Inserts or updates images back in to the Markdown.

Inspiration

To help keep Markdown editing fun for projects needing to add many images which are permutations of a source diagram, this tool will do the heavy lifting.

It is designed for the needs of the Qun mk2 synthesizer project’s README.md guide documentation, originally. Adding images to the guide provides helpful visualizations to teach synthesizer control combinations. Users may refer to pictures in order to activate features on the synthesizer, in addition to text. There are many combinations available with the Qun, and many images to generate, consequently.

So updating 60+ structured images and their Markdown links is work worthy of automation.

Features

Picture is worth 1,000 words

Before:

Button Description
SHIFT + SEQ PLAY + turn dial
 

After, adds images:

Button Description
SHIFT + SEQ PLAY + turn dial
 

and can make animated GIFs:

Button Description
SHIFT + SEQ PLAY + turn dial
The --gif option

Just the big abilities

Usage

Installation

Markdown and high-level options

usage: mdpicgen [-h] --md-file MD_FILE [--md-out-file MD_OUT_FILE]
                [--image-out-dir IMAGE_OUT_DIR]
                [--button-pattern-file BUTTON_PATTERN_FILE]
                [--image-height IMAGE_HEIGHT] [--gif] [--print-formatted]
                [--print-extract]
                {imageset,psd} ...

Parse Markdown table cells into recognized sequences of strings, "keys". Only
matches keys from table columns all identified by patterns in the button-
pattern-file. Inserts and updates links for image files to output Markdown, in
the cells after the keys. Generate images using image layers, named based upon
the keys -- see sub-commands for image generation details.

options:
  -h, --help            show this help message and exit
  --md-file MD_FILE     Input filename for the Markdown file.
  --md-out-file MD_OUT_FILE
                        Output filename for Input Markdown with updated image
                        links.
  --image-out-dir IMAGE_OUT_DIR
                        Output directory name for composited images, will be
                        created (Default: 'out').
  --button-pattern-file BUTTON_PATTERN_FILE
                        Pattern filename for matching buttons (Default:
                        'qunmk2.patset').
  --image-height IMAGE_HEIGHT
                        Pixel height of generated images, used with sub-
                        commands (Default: 48).
  --gif                 Generate GIF from button sequences, sets filename
                        extension (Default: false, use PNG).
  --print-formatted     Print formatted Markdown (from '--md-file') to the
                        console.
  --print-extract       Print sequences to console.

Image generation sub-commands:
  {imageset,psd}        Optional sub-commands for how to generate images: the
                        source of image data.
    imageset            Read image data from a directory of images, supports
                        GIF animation of button sequences.
    psd                 NOT RECOMMENDED: Read image data from PSD file.
                        depends on Adobe(tm) Photoshop tech, slow,
                        incompatibilities between PSD tools unexpectedly
                        breaks workflows, animation not supported.

imageset sub-command

Can be combined with Markdown.

usage: mdpicgen imageset [-h] [--imageset-file IMAGESET_FILE]
                         [--imageset-dir IMAGESET_DIR]

options:
  -h, --help            show this help message and exit
  --imageset-file IMAGESET_FILE
                        Specifies what image filename will be used for what
                        layer, and their xy coordinates.(Default:
                        'qunmk2_imageset.csv')
  --imageset-dir IMAGESET_DIR
                        Directory containing images used as layers defined in
                        '--imageset-file' (Default: 'imageset').

psd sub-command

Can be combined with Markdown.

usage: mdpicgen psd [-h] --psd-file PSD_FILE

options:
  -h, --help           show this help message and exit
  --psd-file PSD_FILE  Input filename for the PSD file.

Details for getting the most out

flowchart LR
    A([INPUT \nMarkdown])
    A1[Extract Sequences from Markdown]

    A2[Generate Images of seqs]
    A3[Generate image links]
    A4[Format each line]
    
    O1([OUTPUT \nImages, linked Markdown, formatted Markdown])

    A --> A1
    
    A1 --> A2
    A1 --> A3
    A --> A4
    
    A2 --> O1
    A3 --> O1
    A4 --> O1
    classDef default fill:#fff,stroke:#000,font-size:12pt;

See a larger diagram of how the data flows, from inputs to outputs.

Workflow

  1. Add a table with customizable "Button" header text as the first column of a Markdown source document, if not already present.
  2. Add button command sequence text, matching the format of the pattern file in use, to a cell in that table’s "Button" column, e.g “SHIFT + B1”.
  3. Add a <br> tag at end of that text, inside the first cell, to mark this button sequence for processing. Repeat as desired.
  4. Run the tool to generate a new Markdown file and images.

Markdown goes in

Images in and out

This script employs sub-commands to generate images.

Output images feature several useful qualities.

Markdown is generated out

Generates image names

Images are named according to their button sequence, with shortened button names.

Button pattern file identifies images

Button pattern files (*.patset) match button sequences, and individual buttons. They define the output image filenames with substrings that map to each individual button in the sequence.

The files are structured similar to CSVs, and use equals (=) instead of commas. They are formatted and line-oriented:

Format Description
^SHIFT$ = s Match a button description with a pattern, and map the button to a substring to be used when naming a generated image for this button.

FORMAT:
[RegEx to match buttons] = [Filename substring, or %digits% macro]

E.g. Here, SHIFT maps to the s in s_splay_d.png for the sample Markdown’s sequence SHIFT + SEQ PLAY + turn dial.
# this is a comment Comment lines with hash-tag (#)
__header__ Identify which tables to parse with this unquoted string. Matches against a table’s first column’s header text contents.
__separator__ Help break-down and split up a long button sequence into individual buttons, with one or more quoted strings. These individual buttons are then matched against the button patterns, above.

A default button pattern file is provided for the Qun mk2 synthesizer.

Matching pattern is powerful

Sample patset

__header__ = Button
__separator__ = "+"
^SHIFT$ = s
^[B]?(utton)?[ ]?\d[ \-a-zA-Z]*( \(Long press\))?$ = %digits%
^(turn)?[ ]?dial[ a-z]*?$ = d
^NO( \(<\))?[ a-z]*$ = n

Imageset CSV input gives visual layout and out filenames

Encode filenames and layer names for all layers matchable in the button pattern file.

A default imageset file and directory is provided for the Qun mk2 synthesizer.

Sample

CSV

image_file,layer_name,x_pos,y_pos,width,height
bg.png,BG,0,0,1856,1236
s.png,s,1572,157
o.png,1,78,631

In files

/imageset
  /bg.png
  /s.png
  /o.png

Examples

Markdown sample:

  1. Notice the first row’s header is Button. This matches the default patset file.
  2. Notice the <br> tag is used only once
    1. With --md-out-file, an image link will be added, if missing.
    2. Or it will be updated, if already in the doc.
  3. Notice the “B1”, “SHIFT”, etc. are configured in the patset file.
|               Button               | Description                         |
|:----------------------------------:|-------------------------------------|
| B1 + B2 <br> ![](/mdpicgen/doc/sample.png) | A button sequence and image         |
|          SHIFT + B3 <br>           | No image. Will injected with image. |
|              SYS + B4              | No br-tag. Won't receive image.     |

At command line – show program options, verbosely

Generate GIF images for a Markdown file to the default out directory

For this script’s README.md to output both PNG and GIF to doc:

Update new Markdown file and generate images for Qun project in a single run

Assumes BASH, changes directory for clarity’s sake, assumes Qun repository is cloned to ../Qun-mk2:

Read a custom button pattern file, and find button sequences in a Markdown file

Utility to format and print a Markdown file

Limitations

Requirements

Thanks

Future

Column two, three (etc.) image placements

Currently, column one is the only column for image extraction and placement. Markdown tables can be written with, or without boundary edge markers (|), which complicates parsing.

| Button                                   | Function                                 |
|------------------------------------------|------------------------------------------|
| SHIFT + SEQ PLAY + turn dial             | <bp> <-BP Inserts image before this text |
| SHIFT + SEQ PLAY + turn dial BPR-> <bpr> | Inserts line-break, and then new image   |
| SHIFT + SEQ PLAY + turn dial BPC-> <bpc> | Inserts new column                       |
| SHIFT + SEQ PLAY + turn dial BPG-> <bpg> | Inserts new GIF                          |