Program Guide

This guide illustrates the ten pipeline stages and explains the program's arguments. Refer to the stages you are working on; you do not need to read the whole guide before starting the lab.

The pipeline smooths the image (stage 1), finds edge pixels (stages 2–6), connects them into paths (stages 7–8), then filters and simplifies those paths (stages 9–10). An edge is a sharp change in brightness. A path is a sequence of connected edge pixels.

Choose a stage, then use the slider to step through its work.

1. Gaussian blur 2. Sobel gradients 3. Magnitude and direction 4. Non-maximum suppression 5. Double threshold 6. Hysteresis 7. Graph construction 8. Path tracing 9. Measure and filter 10. Path simplification

Input

Output

How it works

Details

Example: a 64 x 48 grayscale image. Intermediate images and paths were computed by the repository's C functions and checked against pipeline_run. Image arrays store rows in order, from top to bottom. Pixel (x, y) is at array index y * width + x. Graph and path IDs are indices into the edge_pixels array; each edge pixel stores a position at the center of a pixel.

What the program returns

The C interface (the public API declared in include/) returns a PipelineResult. It contains detected pixels and their connections (EdgePixel records), original paths and their measurements (EdgePath records), and simplified point lists. The SVG displays only the retained, simplified paths. Two drawings can look alike even when these underlying results differ; correctness checks compare the full result using test_pipeline --dump. The Benchmarking guide explains the testing executable and how to run the checks.

Example settings

This 64 × 48 example uses edge thresholds 45 and 140, minimum path length 24, minimum strength 75, and simplification tolerance 1.2. These cutoffs control which edges and paths survive and how much simplification is allowed. They differ from the executable’s defaults listed below.

Running the program

Each successful make benchmark leaves a standalone executable in experiments/NNN/bin/pgm2svg. Run it directly from the repository root on your instance to convert an image using that saved version of the code. For example, replace 001 with the experiment number you want to run:

mkdir -p output
./experiments/001/bin/pgm2svg examples/valve.pgm output/valve

Open output/valve.svg in a browser to view the drawing. You can also use an input saved by the benchmark, such as experiments/001/inputs/curves-2048x2048.pgm.

Alternatively, build your current working source without saving an experiment:

make standalone
mkdir -p output
./bin/pgm2svg examples/valve.pgm output/valve

This builds bin/pgm2svg; bare make does the same. The full command syntax is below. Replace NNN with your experiment number, or use ./bin/pgm2svg after make standalone. Square brackets mark optional arguments; do not type the brackets.

./experiments/NNN/bin/pgm2svg [--benchmark RUNS] INPUT.pgm OUTPUT_PREFIX [LOW HIGH MIN_LENGTH MIN_STRENGTH TOLERANCE]

Supply all five optional parameters or omit them all. The input is a grayscale PGM image at least 5 × 5 pixels. The program writes OUTPUT_PREFIX.svg; the output directory must already exist.

Parameter	Default	Meaning
LOW	22	Minimum nonzero suppressed strength for a weak edge.
HIGH	45	Minimum nonzero suppressed strength for a strong edge.
MIN_LENGTH	8	Minimum original path length, in pixels.
MIN_STRENGTH	0	Minimum mean original gradient strength for a path.
TOLERANCE	1	Maximum simplification error, in pixels.

Thresholds are integers with 0 <= LOW <= HIGH <= 65535. The other parameters must be finite and nonnegative, and tolerance squared must also be finite. RUNS must be a positive integer. See the Benchmarking guide for timing definitions and comparison procedures.