RoundEdge User Manual

A library module from the Persistence of Vision Ray Tracer (POV-Ray) Object Collection.

Abstract

Perfectly sharp edges are rare in real life. Blunting or rounding-off the edges of ray traced objects brings out specular highlights and other, more subtle lighting effects that can make the difference between “That’s a nice ray-traced scene,” and “Wow!”

Unfortunately, with CSG this task is tedious and time-consuming. The standard include file shapes.inc has some helpful macros to assist with this task, but they are rather limited. RoundEdge builds upon shapes.inc and adds some additional objects and functions.

Contents

Overview

Downloaded Files

Contents

Usage

Include this file once prior to using any of the features of RoundEdge:

#include "roundedge.inc"

Including the file more than once is harmless.

Invalid Arguments

The descriptions of the objects assume valid arguments. If the arguments are not valid (for example, a negative radius), then the shape is undefined, with no guarantee of what it will look like or that it will fit anywhere. To assist the user, a warning or error message will be issued.

Prerequisites

There are no external prerequisites. Some of the standard include files are used.

Name Space Compliance

All file names, global identifiers, and local identifiers comply with the Object Collection revised naming standards. The case-insensitive prefixes for this module are “roundedge” and “re.”

Contents

Joint Macros

RE_Round_join (RPost, rBlob)

An instant blob for a vertical cylindrical post joined to a horizontal plane. The joint is at the origin. The bottom surface is slightly below the origin in order to avoid potential coincident surfaces.

Arguments:

RPost:

The radius of the post.

rBlob:

The radius of the blob curve.

Contents

RE_Straight_join_x (Start, End_x, rBlob, Dir)

An instant blob for the intersection between a y-normal plane and a z-normal plane. The object overlaps the line of intersection in the y and z directions in order to avoid potential coincident surfaces.

These arguments may seem odd, but they were chosen to minimize typing and mental effort.

Start:

One end point of the intersection.

End_x:

The scalar x value of the other end point.

rBlob:

The radius of the blob curve.

Dir:

Rotation about the line of intersection, in degrees.

RE_Straight_join_y (Start, End_y, rBlob, Dir)

An instant blob for the intersection between an x-normal plane and a z-normal plane. The object overlaps the line of intersection in the x and z directions in order to avoid potential coincident surfaces.

These arguments may seem odd, but they were chosen to minimize typing and mental effort.

Start:

One end point of the intersection.

End_y:

The scalar y value of the other end point.

rBlob:

The radius of the blob curve.

Dir:

Rotation about the line of intersection, in degrees.

RE_Straight_join_z (Start, End_z, rBlob, Dir)

An instant blob for the intersection between an x-normal plane and a y-normal plane. The object overlaps the line of intersection in the x and y directions in order to avoid potential coincident surfaces.

These arguments may seem odd, but they were chosen to minimize typing and mental effort.

Start:

One end point of the intersection.

End_z:

The scalar z value of the other end point.

rBlob:

The radius of the blob curve.

Dir:

Rotation about the line of intersection, in degrees.

Contents

Edge Macro

RE_Parabolic_torus (H, R)

A circle of radius R parallel to the y-z plane, swept along the curve y = Hx² | z = 0. The user is responsible for bounding. The objects are prone to floating point error, so an isosurface function, RE_fn_Parabolic_torus(), is also provided.

Contents

Rounded Cylinder Macros

RE_Cylinder (A, B, ROuter, rEdge, Use_merge)

A wrapper for macro Round_Cylinder() with several enhancements:

• Scalar end points are automatically expanded to vectors.
• The degenerate cylinder case where the axis is exactly twice the edge radius is intercepted and rendered.
• For the union version, if set as a photons target, photons will be shot at the object as a whole, rather than at its component parts separately. For compact unions such as Round_Cylinder_Union(), this generally results in faster renders. (This feature can be disabled by setting RE_Split_union to on.)

Arguments:

A, B:

The end points of the cylinder.

ROuter:

The radius of the cylinder.

rEdge:

The radius of the edges of the cylinder.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Cylinder_end (A, B, ROuter, rEdge, Use_merge)

A cylinder that is rounded on one end. The resulting object will fit snugly within cylinder { A, B, ROuter }.

Arguments:

A:

The rounded end point of the cylinder.

B:

The flat end point of the cylinder.

ROuter:

The radius of the cylinder.

rEdge:

The radius of the rounded edge.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Hole (A, B, ROuter, RInner, rEdge, Use_merge)

A cylinder with a hole along the central axis. The edges of the hole are rounded. The resulting object will fit snugly within cylinder { A, B, ROuter } and snugly around cylinder { A, B, RInner }.

Arguments:

A, B:

The end points of the cylinder.

ROuter:

The radius of the cylinder.

RInner:

The inner radius of the hole.

rEdge:

The radius of the rounded edges.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Hole_end (A, B, ROuter, RInner, rEdge, Use_merge)

A cylinder with a hole along the central axis. The edge of the hole at one end is rounded. The resulting object will fit snugly within cylinder { A, B, ROuter } and snugly around cylinder { A, B, RInner }.

Arguments:

A:

The end point of the cylinder with the rounded opening.

B:

The end point of the cylinder with the sharp opening.

ROuter:

The radius of the cylinder.

RInner:

The inner radius of the hole.

rEdge:

The radius of the rounded edge.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Hole_minimal (A, B, RInner, rEdge, Use_merge)

A cylinder with a hole along the central axis. The edges of the hole are rounded, and the cylinder is just wide enough to cover the joint between perpendicular rounded boxes of the same edge radius. The object will fit snugly around cylinder { A, B, RInner }.

Arguments:

A, B:

The end points of the cylinder.

RInner:

The inner radius of the hole.

rEdge:

The radius of the rounded edges.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Hole_end_minimal (A, B, RInner, rEdge, Use_merge)

A cylinder with a hole along the central axis. One edge of the hole is rounded, and the cylinder is just wide enough to cover the joint between perpendicular rounded boxes of the same edge radius. The object will fit snugly around cylinder { A, B, RInner }.

Arguments:

A:

The end point of the cylinder with the rounded opening.

B:

The end point of the cylinder with the sharp opening.

RInner:

The inner radius of the hole.

rEdge:

The radius of the rounded edge.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Washer (A, B, ROuter, RInner, rEdge, Use_merge)

A cylinder with a hole along the central axis. The edges of the cylinder and the hole are rounded. The resulting object will fit snugly within cylinder { A, B, ROuter } and snugly around cylinder { A, B, RInner }.

Arguments:

A, B:

The end points of the cylinder.

ROuter:

The outer radius of the cylinder.

RInner:

The inner radius of the hole.

rEdge:

The radius of the rounded edges.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

RE_Washer_end (A, B, ROuter, RInner, rEdge, Use_merge)

A cylinder with a hole along the central axis. The edges on one side of the cylinder and the hole are rounded. The resulting object will fit snugly within cylinder { A, B, ROuter } and snugly around cylinder { A, B, RInner }.

Arguments:

A:

The end point of the rounded side of the cylinder.

B:

The end point of the flat side of the cylinder.

ROuter:

The outer radius of the cylinder.

RInner:

The inner radius of the hole.

rEdge:

The radius of the rounded edges.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

Contents

Rounded Box Macros

Summary

The first macro creates a box with all its edges rounded off. The remaining macros create boxes with only some rounded edges. The intent of the partially rounded box macros is to reduce object counts. This can result in significantly faster renders where differences, intersections, or photons are used.

Despite the large number of macros in this section, there are only four basic shapes: the fully rounded box; and three partially rounded boxes that are pre-rotated into various orientations by the macros.

All of the rounded box macros take the same set of arguments:

A, B:

Opposite points of the box.

rEdge:

The radius of the edges of the box.

Use_merge:

Whether or not to use a merge. In general, pass yes if the object is to be transparent, no otherwise.

The resulting object will fit snugly within box { A, B }.

RE_Box (A, B, rEdge, Use_merge)

A wrapper for macro Round_Box() with two enhancements:

• Scalar end points are automatically expanded to vectors.
• For the union version, if set as a photons target, photons will be shot at the object as a whole, rather than at its component parts separately. For compact unions such as Round_Box_Union(), this generally results in faster renders. (This feature can be disabled by setting RE_Split_union to on.)

Contents

RE_Box_x (A, B, rEdge, Use_merge)

A box with the four edges in the x-direction rounded, like a can of sardines on its side.

RE_Box_y (A, B, rEdge, Use_merge)

A box with the four edges in the y-direction rounded, like a can of sardines.

RE_Box_z (A, B, rEdge, Use_merge)

A box with the four edges in the z-direction rounded, like a can of sardines on its side.

Contents

RE_Box_left (A, B, rEdge, Use_merge)

A box with the four corners on the −x side and the eight adjacent edges rounded.

RE_Box_right (A, B, rEdge, Use_merge)

A box with the four corners on the +x side and the eight adjacent edges rounded.

RE_Box_up (A, B, rEdge, Use_merge)

A box with the four corners on the +y side and the eight adjacent edges rounded.

RE_Box_down (A, B, rEdge, Use_merge)

A box with the four corners on the −y side and the eight adjacent edges rounded.

RE_Box_near (A, B, rEdge, Use_merge)

A box with the four corners on the −z side and the eight adjacent edges rounded.

RE_Box_far (A, B, rEdge, Use_merge)

A box with the four corners on the +z side and the eight adjacent edges rounded.

Contents

RE_Box_x_up (A, B, rEdge, Use_merge)

A box with the two top edges in the x-direction rounded.

RE_Box_x_down (A, B, rEdge, Use_merge)

A box with the two bottom edges in the x-direction rounded.

RE_Box_x_near (A, B, rEdge, Use_merge)

A box with the two edges in the x-direction on the −z side rounded.

RE_Box_x_far (A, B, rEdge, Use_merge)

A box with the two edges in the x-direction on the +z side rounded.

Contents

RE_Box_y_left (A, B, rEdge, Use_merge)

A box with the two edges in the y-direction on the −x side rounded.

RE_Box_y_right (A, B, rEdge, Use_merge)

A box with the two edges in the y-direction on the +x side rounded.

RE_Box_y_near (A, B, rEdge, Use_merge)

A box with the two edges in the y-direction on the −z side rounded.

RE_Box_y_far (A, B, rEdge, Use_merge)

A box with the two edges in the y-direction on the +z side rounded.

Contents

RE_Box_z_up (A, B, rEdge, Use_merge)

A box with the two top edges in the z-direction rounded.

RE_Box_z_down (A, B, rEdge, Use_merge)

A box with the two bottom edges in the z-direction rounded.

RE_Box_z_left (A, B, rEdge, Use_merge)

A box with the two edges in the z-direction on the −x side rounded.

RE_Box_z_right (A, B, rEdge, Use_merge)

A box with the two edges in the z-direction on the +x side rounded.

Contents

Isosurface Functions

Note: In order to avoid a POV-Ray scoping feature, function arguments (other than x, y, and z) are prefixed with “RE_Pn_” in roundedge.inc. In this document, these prefixes are omitted for clarity.

RE_fn_Blob (Value, Blob)

An isosurface blobbing function. This function is based on the formula for POV-Ray’s blob primitive, so it gives identical results when used with f_sphere().

Arguments:

Value:

The unblobbed function value f (x, y, z)

Blob:

“Blobbiness.” Depending on the function, this is typically:

• field radius − surface radius
• field radius ÷ surface radius − 1

Usage:

Subtract RE_fn_Blob() of all base functions from 1. For example:

isosurface
{  function
   {  1 - RE_fn_Blob (abs(x) + abs(z) - 1, 0.3)
        - RE_fn_Blob (f_sphere (0, y, z, 0.8), 0.2)
   }
   max_gradient 4 / 0.2
   contained_by { box { -<2.5, 2, 1>, <2.5, 2, 1> } }
}

RE_fn_Blob2 (Value, Blob)

Another isosurface blobbing function. This function uses an alternate formula that gives smoother curves for some joins than the standard blob formula. Perpendicular planes yield a cylindrical blob with this formula, making it useful in conjunction with the cylinder, sphere, and torus primitives.

Arguments:

Value:

The unblobbed function value f (x, y, z)

Blob:

“Blobbiness.” Depending on the function, this is typically:

• field radius − surface radius
• field radius ÷ surface radius − 1

Usage:

• Add RE_fn_Blob2() of all base functions.
• Take the square root of the sum. (This stabilizes the gradient; it’s well worth the overhead.)
• Subtract from 1.

Example:

isosurface
{  function
   {  1 - sqrt
      (  RE_fn_Blob2 (abs(x) + abs(z) - 1, 0.3)
       + RE_fn_Blob2 (f_sphere (0, y, z, 0.8), 0.2)
      )
   }
   max_gradient 1.3 / 0.2
   contained_by { box { -<2.5, 2, 1>, <2.5, 2, 1> } }
}

Note: the max gradient will typically be inversely proportional to Blob.

Editorial

Why use the blob primitive?

It is highly optimized by the competent POV-Ray team; it’s much faster than isosurface.

Components can have individual textures.

Why use isosurface?

Arbitrary component shapes can be used, not just spheres and cylinders.

Why use RE_fn_Blob() or RE_fn_Blob2() instead of the isosurface blobbing methods suggested in the POV-Ray documentation?

RE_fn_Blob() and RE_fn_Blob2() match the curves of POV-Ray primitives, allowing primitive and isosurface blob to work together. The primitives can then model the bulk of the object, resulting in dramatically shorter rendering times. The illustrations for RE_fn_Hole() and RE_fn_Wheel() demonstrate seamless joins between RE_fn_Blob2() blobs and RE_Straight_join_x().

Contents

RE_fn_Hole (x, y, z, RMajor, rMinor)

A slab with a rounded-edged hole punched through it, equivalent to RE_Hole (-rMinor*y, rMinor*y, ∞, RMajor - rMinor, rMinor, 1). It is intended for use with isosurface blobs.

Arguments:

RMajor:

The major radius of the torus.

rMinor:

The minor radius of the torus.

RE_fn_Parabolic_torus (x, y, z, H, R)

A circle of radius R parallel to the y-z plane, swept along the curve y = Hx² | z = 0. Slower, but better behaved than macro RE_Parabolic_torus(). Check the message window to determine max_gradient.

Contents

RE_fn_Wheel (x, y, z, RMajor, rMinor)

A merge of a torus and a cylinder, equivalent to RE_Cylinder (-rMinor*y, rMinor*y, RMajor + rMinor, rMinor, 1). It is intended for use with isosurface blobs.

Arguments:

RMajor:

The major radius of the torus.

rMinor:

The minor radius of the torus.

Contents

Blob Assist Functions

Note: In order to avoid a POV-Ray scoping feature, function arguments are prefixed with “RE_Pn_” in roundedge.inc. In this document, these prefixes are omitted for clarity.

RE_fn_Blob_distance (Radius, Strength)

Returns the surface radius of a blob, given the field radius and field strength. The default blob threshold of 1.0 is assumed. Use this function when the exact size of a blob component needs to be known. In the illustration, the size of the opening is matched to the blob.

Arguments:

Radius:

The field radius of the component.

Strength:

The field strength of the component.

RE_fn_Blob_radius (Distance, Strength)

Returns the field radius that yields a blob component of the desired surface radius. The default blob threshold of 1.0 is assumed. Use this function when the exact size of a blob component is important. In the illustration, the blob is matched seamlessly to the half-torus.

Arguments:

Distance:

The desired surface radius of the component.

Strength:

The field strength of the component.

RE_fn_Blob_strength (Distance, Radius)

Returns the field strength that yields a blob component of the desired surface radius. The default blob threshold of 1.0 is assumed. Use this function when the exact size of a blob component is important. In the illustration above, the blob is matched seamlessly to the half-torus.

Arguments:

Distance:

The desired surface radius of the component.

Radius:

The field radius of the component.

Contents

Other Identifiers

If the user finds the default values unsatisfactory, they may be modified by declaring them prior to including roundedge.inc. For example:

#declare RE_Split_union = on;
#include "roundedge.inc"

Any identifiers in roundedge.inc that are not documented in this manual are subject to change or elimination in a future update.

Contents

About RoundEdge

Copyright © 2008 Richard Callwood III.

Change Log

User Manual (this document) updated September 4, 2008.

Contents