RENDER(1)

RENDER(1) 💅✨

okay bestie, sit down, hydrate, because this is the Raster3D molecular graphics package rendering program and she is that girl. this is the manual page for render, from the General Commands Manual. no cap. 🎀

---

🌸 NAME 🌸

render — Raster3D molecular graphics package rendering program. she renders. that's it. that's the whole vibe. 💖

---

✨ SYNOPSIS ✨

render < infile.r3d > outfile.png

render -png < infile.r3d > outfile.png

render -avs < infile.r3d > outfile.avs

render [-quality NN] -jpeg < infile.r3d > outfile.jpeg

render -tiff outfile.tiff < infile.r3d

render -sgi [outfile.rgb] < infile.r3d

so like. Render reads an ascii file consisting of several header lines followed by individual object descriptors. those objects get rendered using a fast Z-buffer algorithm to produce a high quality pixel image which contains:

• one light source
• additional non-shadowing light sources
• specular highlighting
• transparency
• Phong shaded surfaces

Output is to stdout [or optional file] in the form of a pixel image with 24 bits of color information per pixel. and the default output format is PNG. iconic behavior honestly. 🌈

---

👑 OPTIONS 👑

• -aa — Force anti-aliasing (SCHEME 4). just force it. demanding queen energy. 💅
• -alpha — Force output of transparency information (SCHEME 0). this ONLY works if the output image format supports an alpha channel (AVS, TIFF, but not JPEG, sorry bestie). note that this turns off anti-aliasing. 🫶
• -avs [outfile.avs] — By default render will produce an PNG image on stdout. the -avs flag will cause it to output an AVS image file instead, or stream the output to stdout if no file is specified. ✨
• -bg white|black|#RRGGBB — Set background color. #RRGGBB is a hexadecimal number representing the red, green and blue components. pick your aesthetic. 🎨
• -draft — Turn off anti-aliasing (SCHEME 1) to increase rendering speed. speed run mode, no jagged-edge shame. 🏃♀️
• -fontscale — Only meaningful in conjunction with the -labels option. Modifies the interpretation of font sizes during label processing. Defaults to -fontscale 3.0, which will generate images whose labels are at the correct nominal font size when printed at 300 dpi. for images to be viewed on the screen, you probably want to set -fontscale 1. 🖨️
• -gamma GG — Apply gamma correction to output image. ✨
• -help — Prints a short summary of command line options. she's helpful like that. 💖
• -invert — Invert image top-to-bottom. this may be necessary if you are using some odd viewing program. no judgment. 🙈
• -jpeg [outfile.jpeg] — By default render will produce an PNG image on stdout. the -jpeg flag will cause it to output a JPEG image file instead, or stream the output to stdout if no file is specified. 🍓
• -labels — Process labels (object types 10, 11, 12) and include them in the rendered image. 📝
• -png [outfile.png] — This is now the default output format. the -png flag will stream the output to stdout if no file is specified. the main character, lowkey. 👑
• -quality — Only meaningful in conjunction with -jpeg option; sets the quality (compression level) of the output image. Allowable values 1 - 100 (default 90). 🎚️
• -[no]shadow — Turn shadowing on or off. the drama is optional. 🌑
• -size HHHxVVV — Override the image size parameters (NTX,NTY,NPX,NPY) in file header and produce an output image that is exactly HHH pixels in the horizontal and VVV pixels in the vertical. 📐
• -sgi [filename.rgb] — Only if compiled with -DLIBIMAGE_SUPPORT. the -sgi flag will cause render to output an SGI libimage style *.rgb file instead of writing to stdout. the filename defaults to render.rgb, but specifying a file on the command line will override this default. 🦋
• -tiff filename — Only if compiled with -DTIFF_SUPPORT. the -tiff flag will cause render to output a TIFF image to the specified file instead of writing to stdout. 🌸
• -transparent — (same as -alpha). Force output of transparency information (SCHEME 0). this only works if the output image format supports an alpha channel (AVS, TIFF, but not JPEG). Note that this turns off anti-aliasing. two names, one icon. 💜
• -zoom ZZ[%] — Rescale image by factor ZZ (ZZ% if the % sign is present). 🔍

---

🎀 HEADER RECORDS 🎀

okay so this is where the actual input file gets its structure, and every single field matters, so pay attention bestie. 💅

• TITLE — Anything you like, up to 80 characters. go feral, it's your title. ✍️
• NTX,NTY — Number of "tiles" in each direction. (The image is rendered piecemeal by dividing it into an array of equal size rectangular tiles.) The width of the output image in pixels is NTX*NPX by NTY*NPY. The speed of the program is sensitive to the number of tiles. However, as a convenience you can set NPX and NPY to zero and use NTX, NTY to provide the net size of the output image in pixels. in this case the program will choose the number of tiles itself so that you don't have to worry about it. she handles it. 🧚
• NPX,NPY — Number of computing pixels per tile in each direction. Maximum = 36 (MAXNPX, MAXNPY in render.f). if you set NPX and NPY to zero, the program will use NTX and NTY as the net size of the image in pixels. ⭐
• SCHEME — Pixel averaging (anti-aliasing) scheme. Anti-aliasing reduces the jaggedness of edges at the cost of additional computation. the full menu:
  • 0 — no anti-aliasing, include alpha blend (matte) channel
  • 1 — no anti-alaising, no matte channel
  • 2 — anti-alias by averaging 2x2 block of computed pixels for each output pixel. Resulting image dimensions are 1/2 of the nominal requested size.
  • 3 — anti-alias by averaging 3x3 block of computed pixels for each 2x2 block of output pixels. Resulting image dimensions are 2/3 of the nominal requested size. (obsolete - use scheme 4 instead)
  • 4 — anti-alias as in scheme 3, but output image dimensions are exactly as requested.

I.e. schemes 0, 1, and 4 produce a NTX*NPX by NTY*NPY pixel image; scheme 3 produces a (2/3)NTX*NPX by (2/3)NTY*NPY image. Scheme 3 requires NPX and NPY to be divisible by 3. Schemes 2 and 4 require NPX and NPY to be divisible by 2. 👑

• BKGND — Background colour (red, green, and blue components, each in the range 0 to 1). 🌈
• SHADOW — T to calculate shadowing within the scene, F to omit shadows. 🌑
• IPHONG — Phong power (e.g., 25) for specular reflections. A smaller value results in a larger spot. the way that works is so real. ✨
• STRAIT — Straight-on (secondary) light source contribution (e.g., 0.15). The primary light source contribution (see also SOURCE below) is given by PRIMAR = 1 - STRAIT. 🔦
• AMBIEN — Ambient reflection quantity (e.g., 0.05). 🫶
• SPECLR — Specular reflection quantity (e.g., 0.25). The diffuse reflection quantity is given by DIFFUS = 1 - (AMBIEN+SPECLR). Ambient and diffuse reflections are chromatic, taking on the specified colour of each object, whereas specular reflections are white. 💅
• EYEPOS — You can think of the image produced by Raster3D as corresponding to a photograph taken by a camera placed a certain distance away from the objects making up the scene. This distance is controlled by the EYEPOS parameter. EYEPOS = 4 describes a perspective corresponding to a viewing distance 4 times the narrow dimension of the described scene. EYEPOS = 0 disables perspective. 📸
• SOURCE — Primary light source position (e.g., 1 1 1). This is a white light point source at infinite distance in the direction of this vector (see note on co-ordinate convention below). The secondary light source is always haed-on. Only the primary light source casts shadows. 💡
• TMAT — Homogeneous global transformation for input objects, given as a 4x4 matrix on 4 lines just as you would write it if you intended it to be a postfix (suffix) operator. The upper left 3x3 submatrix expresses a pure rotation, the lower left 1x3 submatrix gives a translation, the upper right 3x1 submatrix should be zero (otherwise extra perspective is introduced), and the lower right scalar produces global scaling. Coordinate vectors [x y z] are extended with a 1 to make them homogeneous, and then postmultiplied by the entire matrix;

i.e., if

[x' y' z' h'] = [x y z 1][TMAT],

then the ultimate co-ordinates are

[x" y" z"] = (1/h')[x' y' z'].

math girlies rise. 🧮

• INMODE — Object input mode (1, 2, or 3), where mode 1 means that all objects are triangles, mode 2 means that all objects are spheres, and mode 3 means that each object will be preceded by a record containing a single number indicating its type. The Raster3D programs always use mode INMODE 3. the full type roster:

type 1 = triangle
type 2 = sphere
type 3 = round-ended cylinder
type 4   (not used)
type 5 = flat-ended cylinder
type 6 = plane (triangle with infinite extent)
type 7 = normals at vertices of previous triangle
type 8 = material properties for subsequent objects
type 9 = terminate previous material properties
type 10/11/12 = reserved for label processing
type 13 = glow light source
type 14 = quadric surface
type 15 = do not apply TMAT to subsequent objects
type 16 = global rendering properties
type 17 = colors for vertices of preceding triangle or cylinder
type 0 = end of input file

type 4 is not used, don't @ me. 💀

• INFMT or INFMTS — Object input format specifier(s). Normally * for free-format input. ⭐
• SAMPLE HEADER — here's a whole vibe for you to copy, literally verbatim:

Title (This is a 1280x1024 pixel anti-aliased image)
80 64     tiles in x,y
24 24     pixels (x,y) per tile
3         anti-aliasing level 3;  3x3->2x2
0 0 0     black background
F         no shadows cast
25        Phong power
0.25      secondary light contribution
0.05      ambient light contribution
0.25      specular reflection component
4.0       eye position
1 1 1     main light source (from over right shoulder)
1 0 0 0   TMAT matrix describing
0 1 0 0        input coordinate transformation
0 0 1 0
0 0 0 0.6 enlarge by 40% (smaller scalar -> bigger objects)
3         mixed objects
*         (free format triangle descriptors)
*         (free format sphere descriptors)
*         (free format cylinder descriptors)

obsessed. 🌟

---

bestie this is only part 1 — more is coming, don't go anywhere 💖

🗂️ FILE INDIRECTION 🗂️

Okay bestie, this is the part where things get flexible. Anywhere in the input stream to render where an object descriptor would be legal, you can ALSO just drop in a line that starts with @. Yes, literally just an at-sign. That's the whole vibe. 💅

When you do that, the rest of the line after the @ gets read as the name of a file, and further input gets taken from that file instead. So you can stash your fave standard objects somewhere and reuse them across as many rendered scenes as you want — like a set of bounding planes, or your standard definitions of material properties. Chef's kiss, honestly. 🎀

And here's the part that's giving recursion (slay): when input from that level of file indirection ends — specifically, when you hit an object descriptor of type 0 — control returns to the previous input stream. And yes, multiple levels of file indirection are possible. It's files all the way down, no cap. 🦋

Where does it look for these files, you ask? ✨

• Files are first searched for in the current directory.
• If that search fails, they're sought relative to the library directory specified by the environmental variable R3D_LIB.

---

🌈 RASTER3D OBJECT TYPES 🌈

For Raster3D object types and object descriptor formats, go check the man page for r3d_objects. That's the one that has the lore, iykyk. 📖

---

😭 ERROR MESSAGES 😭

Not every error message is a crisis, okay? Some of them can be safely ignored. Deep breaths.

Possible shadowing error NSXMAX= xxx

So what's the tea on this one? It's most usually caused by an object that projects far out of the field of view — think a plane surface, that kind of thing. In most cases, the shadowing "error" is referring to a shadow that lies outside of the image entirely. So like, it's not even in the picture, bestie. Chill.

BUT. 👀 However. If your image does in fact contain missing or truncated shadows, then you can overcome this problem by re-compiling the render program with larger values of NSX and NSY, as indicated by the error message. So the error message is basically telling you its own fix. Iconic behaviour, honestly. 💀

---

🔗 SOURCE 🔗

Want to find the mothership? Here's where:

web URL:

http://www.bmsc.washington.edu/raster3d/raster3d.html

contact:

Ethan A Merritt
University of Washington, Seattle WA 98195
merritt@u.washington.edu

---

👀 SEE ALSO 👀

Go read these too, they're part of the family:

• HTML and PostScript documentation
• r3d_objects(l)
• avs2ps(l)
• rastep(l)
• rods(l)
• ribbon(l)
• balls(l)
• stereo3d(l)

---

👑 AUTHORS 👑

• Originally written by David J. Bacon.
• Extensions, revisions, and modifications by Ethan A Merritt.

---

And that's a wrap on RENDER(1), bestie!! 💖 This whole page is Raster3D V3.0, dated 14 December 2010 — so yeah, it's a vintage queen, but she still ate. 🫶 Go render something gorgeous. ✨🌸