Validate Mosaic Knitting Patterns with pammosaicknit

pammosaicknit checks a mosaic knitting chart for you, turning a black-and-white image into a colour diagnostic that flags every invalid run in red. Allow about ten minutes for a small chart, using the netpbm package, a readable input image and somewhere to write a new output file. The examples use Netpbm 11.5.2 from Ubuntu's netpbm package.

1. Check the installed command

Confirm the executable and the version before relying on a result. This is a read-only check and does not need elevated privileges:

$ command -v pammosaicknit
/usr/bin/pammosaicknit
$ pammosaicknit -version
pammosaicknit: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pammosaicknit: Built from source dated 2024-03-31 09:09:47
...

The installed program prints its version details, then points you to the manual for help. That manual page is dated 12 December 2010, and identifies pammosaicknit as a tool introduced in Netpbm 10.53. The behaviour in this guide is checked against the installed 11.5.2 build.

2. Understand what counts as valid

The input is an image, not a text list of knitting instructions. A valid pattern has a black row at the bottom, then alternating white and black rows moving upwards. In a black row, black pixels can sit anywhere, but there must not be more than three consecutive white pixels. In a white row, the same limit applies to consecutive black pixels.

• Rows wrap horizontally. The first and last pixels in a row are neighbours, so a run can cross the image edge. A white row ending in two black pixels and starting with two more has a run of four black pixels, even though no four-pixel run shows up in a plain left-to-right scan.

There are no pammosaicknit-specific command-line options. The command accepts one optional input filename plus the common libnetpbm options. Omit the filename and it reads standard input; it always writes the diagnostic image to standard output, so redirect that to a new file.

3. Run the validator without overwriting the chart

Use a new destination while testing. Shell redirection with > truncates an existing file before the program starts, so do not point it at the only copy of a useful result:

$ pammosaicknit /path/to/chart.pbm > /path/to/chart-checked.pam

The input can be any Netpbm image, although a black-and-white image expresses the chart most clearly. The output is always a colour Netpbm image with at most four colours: black, white, dark red and light red. On this machine, a successful run produces a PAM file:

$ pamfile /path/to/chart-checked.pam
/path/to/chart-checked.pam: PAM, 4 by 4, RGB, 255 maxval

The dimensions in your output should match the input. Exact wording from pamfile can differ between Netpbm builds; check that the file is identified as a colour image with the right dimensions.

4. Read the red diagnostics

Open the output with an image viewer that understands Netpbm, or convert it with another installed Netpbm tool. Red pixels are the result, not decoration: dark red marks a pixel that was black in the input but needs one or more white pixels for the row rule to hold, and light red marks a pixel that was white but needs one or more black pixels.

If the output has no red pixels, the input is a valid mosaic knitting pattern by these rules. If it does have red, inspect the affected row and remember to count the wraparound connection. The output keeps the same pattern layout, which makes it easier to correct the original chart from the highlighted image than to guess from a bare failure status.

5. Test standard input and non-binary images

A pipeline is useful when the chart is generated by another program. This small PBM example has four columns and four rows, with a black bottom row and alternating rows above it:

$ printf 'P1\n4 4\n0 1 0 1\n1 0 1 0\n0 1 0 1\n1 0 1 0\n' | pammosaicknit > /tmp/chart-checked.pam
$ pamfile /tmp/chart-checked.pam
/tmp/chart-checked.pam: PAM, 4 by 4, RGB, 255 maxval

This only touches the temporary file in /tmp. Use a deliberate, private temporary path when working with a real chart, and move or copy the result to a proper destination once you have checked it. You do not need sudo: validation only needs read access to the chart and write access to the output directory.

If the input is not black and white, pammosaicknit thresholds each pixel's luminosity internally. That is convenient, but it can change a chart whose apparent shades carry meaning. Convert or threshold the source yourself first when you need a reproducible boundary, and keep that prepared input alongside the original for review.

6. Diagnose failures and recover safely

A missing-file error is usually a path or permission problem. Check without changing anything:

$ ls -l /path/to/chart.pbm
$ test -r /path/to/chart.pbm && echo readable

If the output is empty or incomplete, check the command's exit status and the destination size before opening it. Remove only an output you knowingly created for the failed run, then rerun with a new filename. Keep the original chart untouched.