Skip to documentation
BRL-CAD
DocumentationAll documentsEnglish

PIXEMBED(1)

NAME

pixembed - embed a pix image in a larger frame, replicating border pixels

On this page

SYNOPSIS

pixembed [-b border_inset] [-s squareinsize] [-w inwidth] [-n inheight]
         [-S squareoutsize] [-W outwidth] [-N outheight] [in.pix] > out.pix

DESCRIPTION

pixembed reads a 3-byte/pixel RGB pix(5) image and centers it within a larger output pix(5) image. Rather than padding the surrounding border with black, pixembed replicates the boundary pixels of the input outward to fill the entire margin.

Because the extreme edge pixels of an image are sometimes noisy or degraded, the border_inset may be increased so the replicated color is sampled from a row or column slightly inside the actual edge of the input.

If no in.pix is given, the image is read from standard input; the embedded result is always written to standard output. Both input and output dimensions default to 512x512. The output size must be greater than or equal to the input size. The border inset must leave at least one row and one column between the discarded edges; equivalently, each input dimension must be greater than twice the inset.

OPTIONS

-b border_inset

Inset, in pixels, from the actual image edge at which the replicated border color is sampled. The default is 0 (the exact edge pixels are replicated).

-s squareinsize

Set both the width and height of the input image to squareinsize pixels.

-w inwidth

Set the width of the input image to inwidth pixels (default 512).

-n inheight

Set the height of the input image to inheight pixels (default 512).

-S squareoutsize

Set both the width and height of the output image to squareoutsize pixels.

-W outwidth

Set the width of the output image to outwidth pixels (default 512).

-N outheight

Set the height of the output image to outheight pixels (default 512).

EXAMPLES

Example 1. Embed a 512x512 image into a 1024x1024 frame
pixembed -s 512 -S 1024 < input.pix > output.pix

Centers the 512x512 input within a 1024x1024 image, replicating the input’s edge pixels to fill the surrounding border, then writes the larger image to output.pix.

Example 2. Generate a clean matte for compositing
pixembed -w 640 -n 480 -W 800 -N 600 -b 4 render.pix | pix-png -w 800 -n 600 > matte.png

Embeds a 640x480 render into an 800x600 frame, sampling the border color from 4 pixels inside the edge to avoid noisy outer rows, and pipes the result straight into pix-png(1) to produce a PNG ready for compositing.

SEE ALSO

brlcad(1), pixscale(1), pixmatte(1), pixbustup(1), pix-png(1), pix(5)

AUTHOR

BRL-CAD Team

This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org