PIXBORDER(1)

NAME

pixborder - add a 1-pixel-wide border to regions of a specified color

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

pixborder [-a] [-b 'R G B'] [-e 'R G B'] [-i 'R G B'] [-t 'R G B']
          [-B 'H S V'] [-E 'H S V'] [-I 'H S V'] [-T 'H S V']
          [-x _left_edge_] [-y _bottom_edge_] [-X _right_edge_] [-Y _top_edge_]
          [-s _squaresize_] [-w _file_width_] [-n _file_height_] [_file.pix_]

pixborder reads a stream of pix(5) data, finds maximal contiguous regions of a specified interior color, and writes out pix(5) data with every pixel on the boundary of such a region replaced by a border color. (This outlines colored regions; it does not draw a frame around the whole image.) With no input file given, data is read from standard input; output always goes to standard output.

Whether a pixel is on a boundary depends on the interior and exterior colors. The default interior color is 255 255 255 (white) and the default exterior color is 1 1 1. If both or neither color is specified, a pixel is on the boundary when it has the interior color and at least one of its four neighbors (left, right, above, below) has the exterior color. If only one color is specified, a pixel is on the boundary when it matches (or, for an exterior-only specification, does not match) that color and at least one neighbor differs accordingly.

Colors may be given in RGB (channels in {0..255}) or HSV (with H in [0, 360) and S, V in [0, 1]). A symmetric per-channel tolerance (-t or -T) lets nearby colors be treated as the nominal interior or exterior color.

OPTIONS

-a: Autosize: guess the input dimensions from the file (only works for a named pix(5) file, not standard input).
-b 'R G B': Set the border color in RGB. Default is 1 1 1.
-B 'H S V': Set the border color in HSV.
-e 'R G B': Set the exterior (background) color in RGB. Default is 1 1 1.
-E 'H S V': Set the exterior (background) color in HSV.
-i 'R G B': Set the interior (region) color in RGB. Default is 255 255 255.
-I 'H S V': Set the interior (region) color in HSV.
-t 'R G B': Set a symmetric per-channel RGB tolerance for color matching. Default is 0 0 0.
-T 'H S V': Set a symmetric per-channel HSV tolerance for color matching.
-s squaresize: Set both the input width and height to squaresize pixels.
-w file_width: Set the input width in pixels. Default is 512.
-n file_height: Set the input height in pixels. Default is 512.
-x left_edge: Restrict changes to pixels at or to the right of this column. Default is 0.
-X right_edge: Restrict changes to pixels at or to the left of this column. Default is the rightmost column.
-y bottom_edge: Restrict changes to pixels at or above this row. Default is 0.
-Y top_edge: Restrict changes to pixels at or below this row. Default is the topmost row.

EXAMPLES

Example 1. Outline red regions in yellow

pixborder -i '255 0 0' -b '255 255 0' -t '40 40 40' scene.pix > outlined.pix

Outlines every red region (red 255 0 0, with a tolerance of 40 per channel to catch anti-aliased edges) by recoloring its boundary pixels yellow.

Example 2. Draw a multi-pixel-wide border with a pipeline

pixborder -i '255 0 0' -b '0 0 0' scene.pix | \
    pixborder -i '255 0 0' -b '0 0 0' > thick.pix

pixborder only thickens by one pixel per pass, so chaining several invocations in a pipeline widens the border. To build a border of constant-thickness bands of different colors, produce all segments of an outer layer before any of the next inner layer.