SphereSweep 1.2 User Manual

Abstract

[Thumbnail which links to a larger demo image] SphereSweep is a library module from the Persistence of Vision Ray Tracer (POV-Ray) Object Collection.

POV-Ray’s sphere_sweep primitive is a useful object, but it is sometimes prone to artifacts and unreliable automatic bounding. This module provides a variety of alternatives that approximate sphere sweeps using blobs or linear segments. In addition, shapes can be based on Bézier, natural, or quadratic splines, which are not available for the sphere_sweep primitive.

An alternate interface to the actual sphere_sweep primitive is also included.

The control points and radii are specified in arrays.


Table of Contents


Overview

Downloaded Files

The italicized nnnnnn in some of the file names represents the 6-digit number that is in the name of the .zip file.

Key Files
File Description
spheresweep.html The user manual (this document)
spheresweep.inc The SphereSweep software
spheresweep.jpg Sample output
spheresweep_bezier.png Illustrations for the user manual
spheresweep_blob_field.jpg
spheresweep_blob_margin.jpg
spheresweep_cockpit.pov Demonstration scene description files
spheresweep_infinity.pov
spheresweep_lanes.pov
spheresweep_wings.png An image used by one of the demo scenes
READMEnnnnnn.html Important information about using the POV-Ray Object Collection
Other Files
File Description
spheresweep.css A file used by the user manual
spheresweep_icon_diff.png Illustrations for the user manual
spheresweep_icon_opaque.png
spheresweep_icon_transp.png
spheresweep_thumbnail.jpg
spheresweep_description.txt A brief description of SphereSweep
spheresweep_keywords.txt A list of keywords
spheresweep_prereqs.txt Prerequisites (empty file)
cc-LGPL-a.png Administrative files
Versionnnnnnn.js

Table of contents


User Manual Conventions

Capitalization and spacing are significant in this user manual:

SphereSweep (mixed case with no spaces)
Refers to this Object Collection module.
sphere_sweep (all lowercase, monospace font with an underscore)
Refers to POV-Ray’s built-in sphere_sweep primitive.
sphere sweep (two separate words, all lowercase except for sentence capitalization)
Refers to the general concept of sphere sweeps.

Identifiers and file names are presented as-is, using monospace font.

Prerequisites

SphereSweep requires POV-Ray version 3.5 or later.

Namespace Compliance

All file names in this module and all global and local identifiers defined in spheresweep.inc comply fully with the Object Collection naming standards, as revised August 2008 and proposed August 2012. The prefixes for this module are “sswp” and “spheresweep,” including any uppercase and lowercase variants; to avoid conflicts, do not declare identifiers in your scene description file that start with either of these prefixes plus an underscore.

The standard include file shapes.inc is used by spheresweep.inc.

Usage

Include this file once prior to using any of the macros:

#include "spheresweep.inc"

Including the file more than once is harmless, though unnecessary.

POV-Ray may issue a warning that the experimental feature spline is used. This is normal and expected.

Table of contents


Object Macros

Macro Arguments

Spline Types

These values may be used as the Type argument:

The B-splines and Bézier splines are always 3rd order; that is, a curve segment is defined by exactly 4 control points.

Macro SphereSweep_Native() can use only the following spline types:

There are no restrictions for the other object macros.

Array of Spline Control Points

The POV-Ray Spline Workshop has an introduction to spline control points. Although the Workshop only covers 2-D splines, the concepts extend to 3-D space. (There is one difference between the Workshop and the SphereSweep module: SphereSweep does not require an extra point preceding a quadratic spline. This is because this module uses POV-Ray’s experimental spline feature, which does not require the extra point.) The Workshop does not cover B-splines or natural splines, but these are described briefly in the POV-Ray Reference under sphere_sweep and spline, respectively.

The elements of the array of control points (the v_Points argument) are converted internally to 3-D vectors by the macros. An array of 2-D vectors can therefore be used to define an object whose control points are all in the x-y plane.

Array of Sphere Radii

Each value in the array of radii (the Radii argument) corresponds to a spline control point. If this array is shorter than the array of spline control points (v_Points), the last radius will be used for the remainder of the sphere sweep or approximation thereof. This means that you can use an array of one element for a sphere sweep of constant radius. If the Radii array is longer than the array of spline control points, the extra radii are ignored.

Table of contents


SphereSweep_Approx (Type, v_Points, Radii, Res, Tolerance)

A sphere_sweep object (or union, in the case of disjointed Bézier objects) that uses a linear spline to approximate a sphere sweep of another spline type. Note that for opaque objects that are not in a CSG difference or intersection, SphereSweep_Union() renders much faster with the same results (although with a higher object count).

Note: When using the Bézier spline type, if the first sphere of a Bézier segment has a different radius than the last sphere of the previous segment, the segments will be treated as disjoint, even if the respective control points have the same value.

Arguments

Type:
The spline type
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Res:
The number of segments between each pair of adjacent spline control points
Tolerance:
The depth tolerance, as described in the sphere_sweep documentation. For the default tolerance, use 0 (zero).

Table of contents


SphereSweep_Blob_field (Type, v_Points, Radii, Res, Field, Use_Sturm)

An approximation of a sphere sweep using a blob of spheres, with a blob field that varies in proportion to the sphere sweep radii.

Arguments

Type:
The spline type
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Res:
The number of sphere components between each pair of adjacent spline control points
Field:
The blob field radius, in relation to the sphere radii. [Illustration of Field argument] For example, a value of 2 results in a field radius twice the size of each sphere radius.
Use_Sturm:
Boolean; whether or not to use the slower, but more accurate Sturmian root solver.

Table of contents


SphereSweep_Blob_margin (Type, v_Points, Radii, Res, Margin, Use_Sturm)

An approximation of a sphere sweep using a blob of spheres, with a constant blob field margin.

Arguments

Type:
The spline type
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Res:
The number of sphere components between each pair of adjacent spline control points
Margin:
The blob field beyond the sphere radius. [Illustration of Margin argument] For example, if Margin is 0.5 and a sphere’s radius is 2.0, then the field radius will be 2.5.
Use_Sturm:
Boolean; whether or not to use the slower, but more accurate Sturmian root solver.

Table of contents


SphereSweep_CSG (Type, v_Points, Radii, Res, Use_merge)

An approximation of a sphere sweep using a CSG merge or union of linear segments. Note that for transparent objects, or opaque objects in a CSG merge or difference, SphereSweep_Approx() renders faster with the same results.

Arguments

Type:
The spline type
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Res:
The number of segments between each pair of adjacent spline control points
Use_merge:
Whether or not to use a CSG merge. In general, pass yes if the object is to be transparent, no otherwise.

Table of contents


SphereSweep_Merge (Type, v_Points, Radii, Res)

An approximation of a sphere sweep using a CSG merge of linear segments. Although this macro is intended for transparent objects, SphereSweep_Approx() renders these faster with the same results.

Arguments

Type:
The spline type
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Res:
The number of segments between each pair of adjacent spline control points

Table of contents


SphereSweep_Native (Type, v_Points, Radii, Tolerance)

A wrapper for a regular, bona fide sphere_sweep object. If you’re not having any problems with bounding or artifacts, but do have an array of points and an array of sphere radii, you’re all set.

Arguments

Type:
The spline type. Only those spline types supported natively by POV-Ray’s sphere_sweep primitive can be used (SSWP_B_SPLINE, SSWP_CUBIC_SPLINE, and SSWP_LINEAR_SPLINE).
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Tolerance:
The depth tolerance, as described in the sphere_sweep documentation. For the default tolerance, use 0 (zero).

Table of contents


SphereSweep_Union (Type, v_Points, Radii, Res)

An approximation of a sphere sweep using a CSG union of linear segments. In general, use this for opaque objects. Note that in a CSG merge or difference, SphereSweep_Approx() renders faster with the same results.

Arguments

Type:
The spline type
v_Points:
An array of spline control points
Radii:
An array of sphere radii corresponding to the spline control points
Res:
The number of segments between each pair of adjacent spline control points

Table of contents


Utility Macros and Function

Macro SSwp_Bezier (v_Ctrls, s_File, VDim, Places)

As a convenience for facilitating continuity between Bézier spline segments, this macro accepts a set of points and vectors, and converts them to an array of Bézier control points. The returned array may be passed directly to a SphereSweep object macro; or its elements may be used to construct a lathe or prism primitive. Optionally, the points may be written to a file.

[Illustration of the set of points and vectors] The set of points and vectors is an n×3 array, where n is the number of distinct points through which the spline passes. For this array, the last point of a Bézier segment and the first point of the next segment are considered to be the same point. Each element [][1] is a point through which the spline passes. Elements [][0] and [][2] are vectors pointing to the previous and next intermediate control points, respectively, in the spline. The spline does not typically pass through the intermediate control points. By making these vectors collinear, while pointing in opposite directions, smooth transitions may be maintained between spline segments.

Elements [0][0] and [n − 1][2] are ignored.

The illustration shows an example of how this array translates to the final set of control points.

Arguments

v_Ctrls:
The array of points and vectors. This argument is input only and is not altered.
s_File:
The name of a file to which to write the output array. Use "-" (hyphen) to write to the debug stream or "" (the null string) for no written output.
VDim:
The dimension size of the points to be written to the file
Places:
The number of decimal places to be written

Table of contents


Function SSwp_fn_Blob_strength (RSurface, RField)

Returns the field strength that yields a blob component of the desired surface radius. The default blob threshold of 1.0 is assumed.

This function is used internally by macros SphereSweep_Blob_field() and SphereSweep_Blob_margin(), but is too useful not to document. More blob-related functions are available from the Object Collection module RoundEdge.

Arguments

Note: In spheresweep.inc, the function arguments are prefixed with “sswp_Pn_” in order to avoid a POV-Ray namespace scope feature. These prefixes are omitted here for clarity.

RSurface:
The desired surface radius of the blob component
RField:
The field radius of the component

Table of contents


Macro SSwp_Subarray (Array, Start, End)

Returns a one-dimensional array that is a copy of a subrange of another one-dimensional array.

Arguments

Array:
The array to be copied
Start:
The index of the first element to be copied
End:
The index of the last element to be copied

Table of contents


Other Identifiers

Identifier Type Description Value
SPHERESWEEP_VERSION float The SphereSweep version, in case the scene file needs that information. 1.2

Internal Identifiers

Any identifiers in spheresweep.inc that are not documented in this manual are considered “private” or “protected,” and are subject to change or elimination in a future update.

Table of contents


Observations

Artifacts

For B-splines and cubic splines, the following alternatives are free of tracing artifacts (although banding artifacts may appear if the value of Res is too low):

Render Speeds

These observations are not hard and fast rules. All timing tests were done using POV-Ray 3.7.

Table of contents


About SphereSweep

Copyright © 2013, 2015 Richard Callwood III. Some rights reserved. Licensed under the Creative Commons-GNU Lesser General Public License.

Object Collection Categories

Change Log

Version Date Notes
1.0 2013 July 22
  • The module is created.
1.1 2015 August 28
  • B-spline capability is added for most of the object macros.
1.2 2015 September 11
  • Bézier spline capability is added for most of the object macros.

Table of contents