Validate Mosaic Knitting Patterns with pammosaicknit

You will turn a black-and-white Netpbm chart into a colour diagnostic image, then use the red pixels to find invalid runs in a mosaic knitting pattern. Allow about ten minutes for a small chart. You need the netpbm package, a readable input image and somewhere to write a new output file. The commands below 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 and then says to use the manual for help. The manual page is dated 12 December 2010, and identifies pammosaicknit as a tool introduced in Netpbm 10.53. The behaviour in this guide is verified 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, followed by alternating white and black rows as you move upwards. In a black row, black pixels may be arranged freely, but there must not be more than three consecutive white pixels. In a white row, the equivalent limit is three consecutive black pixels.

Rows wrap horizontally. The first and last pixels in a row are neighbours, so a run can cross the image edge. For example, a white row ending in two black pixels and beginning with two black pixels has a run of four black pixels. That row is invalid even though no four-pixel sequence appears in a simple left-to-right scan.

There are no pammosaicknit-specific command-line options. The command accepts one optional input filename and also accepts common libnetpbm options. If you omit the filename, it reads standard input. It writes the diagnostic image to standard output, so redirect that output 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 and that its dimensions are right.

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 must contain one or more white pixels for the row rule to hold. Light red marks a pixel that was white in the input but must contain one or more black pixels.

If the output contains no red pixels, the input represents a valid mosaic knitting pattern according to these rules. If it contains red, inspect the affected row and include the wraparound connection when counting the run. The output retains the same pattern layout, which makes it safer to correct the original chart from the highlighted image rather than guessing from a 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 changes only the temporary file in /tmp. Replace it with a deliberate, private temporary path when working with a real chart. If you want to keep the result, move or copy it to a destination after checking it. Do not use sudo: validation normally needs only 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 conversion 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. If you accidentally redirected over an existing diagnostic image, recovery depends on your backups or filesystem snapshots; pammosaicknit has no undo operation.

Malformed Netpbm input can also make the run fail. Confirm the source with pamfile or another trusted Netpbm reader before changing the chart. Do not treat a viewer's failure to open the output as evidence that the knitting rules passed: first verify the PAM header, then inspect the image with a compatible tool.