'\" t
.\"     Title: OVERLAY
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 08/28/2023
.\"    Manual: BRL-CAD User Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "OVERLAY" "nged" "08/28/2023" "BRL\-CAD" "BRL\-CAD User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
overlay \- Plots the specified UNIX \fIplot_file\fR in the MGED display\&.
.SH "SYNOPSIS"
.HP \w'\fBoverlay\fR\ 'u
\fBoverlay\fR [\fI\-s\ #\fR] [\fI\-N\ viewobj_name\fR] {\fIplot_file\fR} [\fIviewobj_name\fR]
.HP \w'\fBoverlay\ \-F\fR\ 'u
\fBoverlay \-F\fR [\fI\-i\fR] [\fI\-c\fR] [\fI\-z\fR] [\fI\-X\ #\fR] [\fI\-Y\ #\fR] [\fI\-w\ #\fR] [\fI\-n\ #\fR] [\fI\-S\ #\fR] [\fI\-\-format\ fmt\fR] {\fIimg_file\fR}
.SH "DESCRIPTION"
.PP
Plots the specified UNIX
\fIplot_file\fR
in the current application display or the specified
\fIimage file\fR
in the current application embedded framebuffer\&. When displaying plot files, multiple files may be specified using a pattern match (e\&.g\&.,
\fBoverlay\fR
\fI*\&.plot\fR)\&.
.PP
When displaying plot files, phony object names are created for each part of the plot file(s) with a unique color\&. The names are created by adding a color to the specified
\fIviewobj_name\fR, or to _PLOT_OVERLAY_ if no name is provided\&. The color suffix is built by converting the RGB color to a six\-digit hex number\&. Each color corresponds to 2 hex digits, so that white becomes "ffffff," red becomes "ff0000," green is "00ff00," etc\&.
.PP
Image files will be display in the currently active framebuffer\&. Currently multiple images cannot be specified by a single
\fBoverlay\fR
command (but as the images would overrwrite each other this feature would not be terribly useful in any case\&.) However, mulitiple images can be written in succession to the same framebuffer using the
\fB\-X\fR
and
\fB\-Y\fR
offset specification options to offset their positions for simultaneous display\&. Alternately, if the user wishes to reset the framebuffer before drawing the new image the
\fB\-c\fR
option may be specified\&.
.PP
The
\fB\-w\fR,
\fB\-n\fR, and
\fB\-S\fR
options are used to specify image size for formats such as PIX that do not encode the image size in their own data\&. Similarly,
\fB\-\-format\fR
may be used to explicitly specify an image format if the filename does not make the format clear\&.
.PP
By default, images are displayed in the framebuffer using their original size\&. If the users wishes to use all available space in the image window to display an image, the
\fB\-z\fR
may be specified to focus the framebuffer on the image\&. The
\fB\-i\fR
option may be used to invert an image\*(Aqs display in the y (vertical) direction\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Plot a UNIX plot file in the MGED display.\fR
.PP

mged>\fBoverlay plot\&.upl tmp\fR
.PP
Plots the UNIX plot file
\fIplot\&.upl\fR
in the MGED display, using
\fItmp\fR
as the base for the phony object names\&.
.PP
\fBExample\ \&2.\ \&Plot a PNG file in the MGED framebuffer.\fR
.PP

mged>\fBoverlay \-c \-F image\&.png\fR
.PP
Plots the image file
\fIimage\&.png\fR
in the MGED framebuffer, first clearing any pre\-existing images in the framebuffer\&.
.SH "AUTHOR"
.PP
BRL\-CAD Team
.SH "BUG REPORTS"
.PP
Reports of bugs or problems should be submitted via electronic mail to
devs@brlcad\&.org
