R3D_OBJECTS(1)

🦋 R3D_OBJECTS(1) — General Commands Manual 🦋

okay so bestie, this is the R3D_OBJECTS page from the General Commands Manual, and it's literally the dictionary of every object descriptor type the Raster3D crew understands. no cap, every one of these has a required parameter list and you gotta get them exactly right or the renderer will simply not know what you're on about. let's go 💅

---

✨ NAME ✨

rd3_objects — object types used by the Raster3D package

(yes, the manpage spells it rd3_objects. we're keeping it. it's iconic, it's canon, don't @ me 🫶)

---

🌸 DESCRIPTION 🌸

these are the object descriptor types, plus the required parameters, that the render program and the rest of the Raster3D package actually recognize. if it's not on this list, it's not a thing. periodt.

---

🔺 Object type 1 - triangle

x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue;

three points, three color channels. that's the whole vibe.

---

🔮 Object type 2 - sphere

x, y, z, radius, red, green, blue;

center, radius, color. so clean, so simple, love that for us.

---

🥫 Object type 3 - cylinder with round ends

x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue.

quick note bestie: R1 is the cylinder radius, and R2 is currently ignored (it's just there. sitting there. being ignored. 😭).

---

🚫 Object type 4 - not used

literally nothing. it's giving "left on read". moving on.

---

📏 Object type 5 - cylinder with flat ends

x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue.

same deal as type 3: R1 is the cylinder radius, R2 is currently ignored.

---

🪞 Object type 6 - plane

x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue;

any three points define the plane — that's it, that's the whole rule. and its color fades from full intensity in the foreground to half-intensity at the back. gradient moment ✨

---

📐 Object type 7 - Vertex normals

explicit vertex normals for the preceding triangle object. it must directly follow the triangle object, and it uses the same format. no spacing out, no other objects in between, they're attached at the hip fr fr.

---

🎨 Object type 8 - Material properties.

these values override the lighting and specular highlighting specs from the header records, so some objects can flex different surface properties than everyone else. the specified values apply to all subsequent objects until an object of type 9 shows up. the parameters are read as free format floating point numbers from the next line of the input stream:

8
MPHONG MSPEC SR SG SB CLRITY OPT1 OPT2 OPT3 OPT4

• MPHONG — a value >=0 overrides the global Phong power for specular highlighting
• MSPEC — a value >=0 overrides the global specular scattering contribution
• SR,SG,SB — RGB triple specifying the color of reflected light (by default all specular highlights are white). a negative value for any component will default to the base colour component of the object being rendered.
• CLRITY — the degree of transparency for this material, with 0.0 indicating an opaque surface and 1.0 a purely transparent one
• OPT1 — affects processing of transparent objects which belong to the same material, but occlude each other (for instance the front and back surfaces of a transparent molecular surface).
  • OPT1 = 0 will render all outward-facing transparent surfaces
  • OPT1 = 1 will render only the topmost outward-facing surface
  • OPT1 = 2 will render both the outward- and inward- facing surfaces of transparent spheres and cylinders
• OPT2 — selects from several variant treatments of transparency as a function of alpha and the Z component ZN of the surface normal.
  • OPT2 = 0 T(ZN) = 0.25(1+cos(pi*alpha*ZN)^2
  • OPT2 = 1 T(ZN) = (1-abs(alpha*ZN))^2
  • OPT2 = 2 T(ZN) = 1 - alpha ^ (cos(pi/4) / abs(ZN))
  • OPT2 = 3 T(ZN) = 1 - alpha

Option 0 is an empirical function that the author thinks looks good. (trust the process 💖)

• OPT3 — not used
• OPT4 — non-zero to indicate that additional modifier records follow immediately. each modifier must constitute a single line, and OPT4 tells how many of these lines there will be. here's a complete list of modifiers currently available, and their parameters:
  • SOLID RED GREEN BLUE
  • BACKFACE RED GREEN BLUE MPHONG MSPEC
  • FRONTCLIP ZFRONT
  • BACKCLIP ZBACK
  • BOUNDING_COLOR RED GREEN BLUE
  • BOUNDING_PLANE BPTYPE X Y Z Xnorm Ynorm Znorm
  • ORTEP_LIKE used to create fancy ellipsoids (see rastep documentation)

---

🔚 Object type 9 - End_material

terminates application of all previously defined special material properties (object type 8) or isolation from TMAT transformation (object type 15). it's the "okay we're done here" of descriptors 🎀

---

🏷️ Object types 10,11,12 - Label descriptors

these object types are used as label descriptors. the current version of render ignores them unless the -labels option is selected on the command line. (the disrespect honestly 😭)

Object type 10 - font_name size alignment

legal values subject to details of font processing implementation.

• font_name is any font name recognized by libgd
• size is the font size in points, but is modified by render's -fontscale option
• alignment is "Left", "Right", "Center", or "Offset".

Object type 11 - Label text

X Y Z R G B     (On one line) label position and color
Label text      (On 2nd line)

two lines, one job. 💅

---

💡 Object type 13 - Glow light source.

this is a colored, non-shadowing, light source with finite [x y z] coordinates and a limited range of illumination. control parameters are read in free format from a single line of input following the line specifying the object type.

13
GLOWSRC(3) GLOWRAD GLOW GOPT GPHONG GLOWCOL(3)

• GLOWSRC(3) — [x y z] coordinates of light source
• GLOWRAD — limiting radius of light source (see GOPT)
• GLOW — fractional contribution (0.0 - 1.0) of glow light to total lighting model
• GOPT — (integer 0/1/2/3/...) controls functional form in which limiting radius is applied [under development]
• GPHONG — Phong parameter controlling specular highlights from glow light
• GLOWCOL(3) — RGB triple specifying color of glow light source

heads up: GOPT is marked [under development] in the original. so it's giving "work in progress", not "fully baked". 🌈

---

🥚 Object type 14 - Quadric surface

x, y, z, limiting_radius, red, green, blue, A, B, C, D, E, F, G, H, I, J

quadric surfaces include spheres, cones, ellipsoids, paraboloids, and hyperboloids. the motivation for this code was to allow rendering thermal ellipsoids for atoms, so the other shapes have not been extensively tested. (tested-enough energy 🙈)

a quadric surface is described by 10 parameters (A...J). although these parameters are sufficient to describe a quadric surface located anywhere, for efficiency during rendering it's also useful to know the center and a bounding sphere. so by convention we require that (A...J) describe a surface centered at the origin, and add additional parameters x, y, z to add a translation component. therefore a QUADRIC descriptor to render has the 17 parameters listed above.

the surface is the set of points for which Q(x,y,z) = 0 where

Q(x,y,z) = Ax2 + By2 + Cz2 + 2Dxy + 2Eyz + 2Fzx + 2Gx + 2Hy + 2Iz + J

points further from the origin (prior to translation!) than the limiting radius are not rendered. so like, know your radius bestie.

---

🔒 Object type 15 - TMAT Isolation

objects following this descriptor are interpreted as being in an absolute coordinate system centered at the origin and having unit extent in X, Y, and Z. if the image is rectangular, coordinates run from -0.5 to +0.5 along both X and Y. if the image is rectangular, coordinates run from -0.5 to +0.5 along the shorter dimension. (yes, the page says "if the image is rectangular" twice. we do not editorialize. we copy. 🫶)

the rotation and translation described by the TMAT matrix is not applied. this isolation from TMAT applies to subsequent objects until an object of type 9 is encountered.

---

🌍 Object type 16 - Global property

object type 16 is always followed by a single record that affects the rendering of the entire scene. currently the options are FOG, FRONTCLIP, and BACKCLIP. there are also options ROTATION and TRANSLATION that affect only objects following their appearance in the input stream. so like — some of these are whole-scene main characters, and some only care about what comes after them. 👑

---

🌈 Object type 17 - Vertex colours

explicit vertex colours for preceding triangle or cylinder object.

R1 G1 B1   R2 G2 B2   R3 G3 B3

---

🫥 Object type 18 - Vertex transparency

explicit transparency at vertices of preceding object. all three values are required, though only the first two are used for cylinders, and only the first one for spheres.

Trans1 Trans2 Trans3

---

🔒✨ Object type 19 - TMAT Isolation

similar to object type 15, except the the x and y scales are the same only in the case of a square image. both the x and y axes run from -0.5 to +0.5 regardless of the aspect ratio of the rendered image. (and yes — "the the". we see it. we love it. we keep it. 💜)

---

👀 SEE ALSO 👀

• PostScript and HTML documentation
• render(l)

---

and that's the whole page bestie, you ate that 💅 the source is Raster3D, dated 8 May 1999 — yes, 1999, she's a vintage icon and she still slays 👑✨ go render something gorgeous, mwah 🎀🦋💖