BRLCAD(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

🌸 BRLCAD(1) — the BRL-CAD fam, explained 💅

okay so bestie, welcome to the BRL-CAD manual page (section 1, the one for actual programs you run) — and no cap, this is your map to the whole entire distribution: solid modeling, raytracing, graphics, and image processing. It's giving "big library energy" and honestly? iconic.

✨ NAME ✨

brlcad — the BRL-CAD programs for solid modeling, raytracing, graphics, and image processing. that's the whole vibe. 🦋

🎀 DESCRIPTION 🎀

The BRL-CAD Distribution is literally so many directories of materials — programs, man pages, documents, libraries, etc. — and the major categories of programs are, in order, bestie:

  • mged — a multi-device interactive editor for constructing and updating combinatorial solid geometry (CSG) models. see mged(1), and also Understanding the Preparation and Analysis of Solid Models by Michael John Muuss (enclosed, in the "paper" directory). queen behavior. 👑
  • librt — a library of functions suitable for interrogation of a CSG solid model, utilizing ray-tracing techniques. see librt(3).
  • rt — a ray-tracing lighting model, for rendering pictures of mged(1) CSG models. see rt(1), rtray(1), rtpp(1).
  • conv — programs to convert mged(1) and pix(3) format binary files to a portable ASCII form, and back again. see asc2g(1), asc2pix(1), conv-vg2g(1), g2asc(1), pix2asc(1). round-trip slay. 🔁
  • libpkg — a "message-passing" interface layered on top of TCP network links, to ease construction of network-distributed applications.
  • libfb — a generic frame-buffer library which includes support for a number of display devices, as well as file, network, and debugging interfaces. most programs which use this library have the letters "fb" in their names. to override your system default frame-buffer, the environment variable FB_FILE can be set. in addition, some commands also support a -F framebuffer option. note that the disk file format of libfb is that of pix(5), allowing "framebuffer" files to be later processed by any of the "pix" family of programs. see libfb(3), pix-fb(3), pix(5), etc. 💖
  • fbserv — TCP-based network server which implements remote frame-buffer services.
  • libplot3 — a public-domain version of the UNIX-Plot library which differs from that of the standard libplot(3), by the addition of 3-D primitives, color, floating point coordinate routines, and the use of a file pointer parameter. see libplot3(3), plot3(5).
  • librle — a Run-Length-Encoding (RLE) library, providing functions originally from the University of Utah in a library package. note that the current version of this library reads Edition-3 RLE files. see rle-fb(1), fb-rle(1), rle-pix(1), pix-rle(1), librle(3).
  • util — a collection of image-handling utilities, each constructed as individual tools intended to be used in combination. see ap-pix(1), bw-fb(1), bw-imp(1), bw-pix(1), bw3-pix(1), bwcrop(1), bwdiff(1), bwfilter(1), bwhist(1), bwmod(1), bwrect(1), bwrot(1), bwscale(1), bwstat(1), dunncolor(1), dunnsnap(1), fb-bw(1), fb-pix(1), fb-rle(1), fbanim(1), fbclear(1), fbcmap(1), fbcmrot(1), fbcolor(1), fbframe(1), fbgrid(1), fbpoint(1), fbzoom(1), gencolor(1), loop(1), pix-bw(1), pix-bw3(1), pix-fb(1), pixbackgnd(1), pixbustup(1), pixdiff(1), pixfilter(1), pixhist(1), pixhist3d-plot3(1), pixhist3d(1), pixinterp2x(1), pixrect(1), pixrot(1), pixscale(1), pixstat(1), pixtile(1), plot3-fb(1), rle-fb(1), rle-pix(1), wavelet(1), bw(5), pix(5), plot3(5). that's the whole squad. 🫶
  • vdeck — a program to convert mged(1) models to gift(1) format card deck files. see vdeck(1).

💜 FB_FILE 💜

so whenever a framebuffer is needed, and the -F option has not been specified, the environment variable FB_FILE gets checked for the device to use. the format of this variable is either:

[hostname:]/dev/device_name[num]

or UNIX_path, the pathname of a disk file to be used as a "virtual framebuffer".

some deets bestie:

  • Hostname is the name of a remote machine if the remote framebuffer interface is being used.
  • when a local display device is being specified, the hostname should not be specified, for performance reasons; just the special string device_name is used to select a particular type of framebuffer.
  • Num is type dependent and can either mean a display number or select some options for that type.
🚨 note that for security reasons, it is not permitted to access a disk file via the remote interface.

if FB_FILE is not set, the default for your system will be used.

the use of /dev/ before the device_name is simply to distinguish them from filenames. see the end of the libfb(3) manual page for a list of the device names and the meanings of any num parameters they may take, and for a more detailed discussion. 🌈

✨ OPTIONS ✨

so there's a whole convention for the options used on most of the utilities provided, and honestly it's lowkey adorable:

  • random options are usually lower case.
  • options which could specify either a screen or file size are, by convention, lower case for file information, and UPPER CASE for screen information. iykyk. 🎀

here's a list of some of the common options you may encounter, bestie:

  • -F framebuffer — specifies the framebuffer device or virtual framebuffer file to use, overriding the FB_FILE environment variable or system defaults. main character flag fr. 👑
  • -i — inverse flag. pretend origin is in upper left corner of screen, for that good old-fashioned fourth-quadrant behavior. retro moment. 🦋
  • -c — various. typically means clear the screen first.
  • -z — various. typically means zoom-in on current area of display.
  • -s square_file_size — specifies the file size for a square image.
⚠️ WARNING: behavior is undefined when the -s flag is used in conjunction with the -w or -n flags. like bestie don't do it, it's giving chaos. 💀
  • -w file_width — specifies the width of the file to be processed.
  • -n file_height — specifies the height of the file to be processed.
  • -S square_screen_size — specifies the screen size for a square display.
⚠️ WARNING: behavior is undefined when the -S flag is used in conjunction with the -W or -N flags. same energy, still don't. 💀
  • -W screen_width — specifies the width of the screen display.
  • -N screen_height — specifies the height of the screen display.
  • -x file_x_offset — specifies the X-coordinate offset for the file.
  • -y file_y_offset — specifies the Y-coordinate offset for the file.
  • -X screen_x_offset — specifies the X-coordinate offset for the screen display.
  • -Y screen_y_offset — specifies the Y-coordinate offset for the screen display.
  • -# bytes_per_sample — specifies the number of bytes per sample, where the # character is a literal "pound" or "sharp" sign character, typically found over the numeral "3" on ANSI keyboards. several programs (like pixrect) can operate on data samples of arbitrary width. for example, a pix(5) format file can often be treated like a bw(5) format file with a width of three bytes per sample. ✨

🍓 TAPE FORMAT 🍓

okay so when dealing with large collections of images, as might be needed for making a movie, it frequently becomes desirable to deal with magnetic tapes. some of the early pix(5) tools contained built-in knowledge of the tape format. while this aberrant early design has been corrected in favor of using tape-oriented programs such as dd(1) in pipelines with the image tools, our "standard" image format remains.

regardless of image resolution, all tape records are 24k bytes long. if an image does not occupy an integral number of tape records, the last record is padded out. for example, NTSC images in 640x480 format use 37.5 records per image. the files-tape(1) utility is helpful in performing this function.

the capacity of an average 2400 foot reel of tape at 6250 is 6144 records of 24k bytes each. for the various combinations of density and image resolution, a convention for the number of frames/reel exists:

Density / Resolution / Frames per reel:

  • 6250 / 1k / 48
  • 6250 / 640x480 / 160
  • 6250 / 512 / 192
  • 1600 / 1k / 12
  • 1600 / 512 / 48

numbers don't lie bestie. 🎀

🌸 EXAMPLES 🌸

the following examples demonstrate typical usage of some common BRL-CAD system features and environment variables. let's gooo. 🔥

Example 1. Setting the default framebuffer

to set the default framebuffer device to a specific X11 window using an environment variable, which many BRL-CAD display utilities will then use automatically:

export FB_FILE=/dev/X

Example 2. Viewing a rendered image

to display a rendered pix format file on the default framebuffer, scaling the image to a square screen size of 1024:

pix-fb -S 1024 image.pix

literally that easy. 💅

🧚 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. don't be shy, they wanna hear it. 🙈

and that's the whole page bestie — this was BRL-CAD, from the BRL-CAD manual, page BRLCAD(1) (the footer's just the source name BRL-CAD chillin' on the left and BRLCAD(1) holding it down on the right). go build something iconic. ⭐💖

📦 where this page comes from