SphereSweep is a library module from the Persistence of Vision Ray Tracer (POVRay) Object Collection.
POVRay’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.
The control points and radii are specified in arrays.
Also included in this module are an alternate interface to the actual sphere_sweep
primitive, macros for copying subarrays and for creating control points for smooth Bézier curves, and a function for controlling blob sizes.
New in version 2.0 are data conversion to and from Blue Herring’s PointArrays module, and a more robust Bézier algorithm.
The italicized nnnnnn in some of the file names represents the 6digit 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_bezier.png 
Illustrations for the user manual 
spheresweep_blob_field.jpg 

spheresweep_blob_margin.jpg 

spheresweep_splines.png 

spheresweep_cockpit.pov 
Demonstration scene description files 
spheresweep_infinity.pov 

spheresweep_infinity_pa.pov 

spheresweep_lanes.pov 

spheresweep.jpg 
Sample output images 
spheresweep_thumbnail.jpg 

spheresweep_wings.png 
An image used by one of the demo scenes 
Administrative Files  
File  Description 
README nnnnnn.html 
Important information about using the POVRay Object Collection 
spheresweep_description.txt 
A brief description of SphereSweep 
spheresweep_keywords.txt 
A list of keywords 
spheresweep_prereqs.txt 
Prerequisites 
spheresweep.css 
Other administrative files 
ccLGPLa.png 

Version nnnnnn.js 

Other Files  
File  Description 
spheresweep_icon_diff.png 
Icons for the user manual 
spheresweep_icon_opaque.png 

spheresweep_icon_transp.png 
Capitalization and spacing are significant in this user manual:
sphere_sweep
(all lowercase, monospace font with an underscore)
sphere_sweep
primitive.
Identifiers and file names are presented asis, using monospace font.
spheresweep_infinity_pa.pov
, requires the PointArrays module and POVRay 3.6.1 or later. PointArrays is not required for general use of SphereSweep.
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 reserved prefixes for this module are “spheresweep
” and “sswp
,” including any uppercase and lowercase variants. To avoid conflicts, do not introduce into your scene description file any identifiers with these names, or any identifiers that start with these names plus an underscore.
The standard include file shapes.inc
is used by spheresweep.inc
. The identifier View_POV_Include_Stack
from the standard include file debug.inc
is referenced by spheresweep.inc
, although debug.inc
itself is not used.
Include this file once prior to using any of the macros:
#include "spheresweep.inc"
Including the file more than once is harmless, though unnecessary.
POVRay may issue a warning that the experimental feature spline is used. This is normal and expected.
The POVRay Spline Workshop has an introduction to spline control points. Although the Workshop only covers 2D splines, the concepts extend to 3D 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 POVRay’s experimental spline feature, which does not require the extra point.) The Workshop does not cover Bsplines or natural splines, but these are described briefly in the POVRay Reference under sphere_sweep
and spline
, respectively.
The elements of the array of control points (the pv_Points
argument) are converted internally to 3D vectors by the macros. An array of 2D vectors can therefore be used to define an object whose control points are all in the xy plane.
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 (pv_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.
These values may be used as the Type
argument:
SSWP_B_SPLINE
SSWP_BEZIER_SPLINE
C
’ path. This curve comprises a series of segments, each of which is defined by exactly 4 control points. Each curve segment starts and ends at its 1st and 4th control points, respectively, but typically does not pass through the 2nd and 3rd control points.
SSWP_CUBIC_SPLINE
SSWP_LINEAR_SPLINE
SSWP_NATURAL_SPLINE
SSWP_QUADRATIC_SPLINE
Note: SSWP_QUADRATIC_SPLINE
is not the same as the SVG quadratic ‘Q
’ path; to get the SVG equivalent, use SSWP_BEZIER_SPLINE
, and set the control points of each Bézier segment as follows:
where Q1 and Q3 are the SVG endpoints, Q2 is the SVG middle control point, and P1...P4 are the SphereSweep control points.
Macro SphereSweep_Native()
can use only the following spline types:
SSWP_B_SPLINE
SSWP_CUBIC_SPLINE
SSWP_LINEAR_SPLINE
There are no restrictions for the other object macros.
A sphere_sweep
object (or union of sphere_sweep
objects, 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.
Formal Parameter  Type  Description 

Type 
float  The spline type 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Res 
float  The number of segments between each pair of adjacent spline control points 
Tolerance 
float  The depth tolerance, as described in the sphere_sweep documentation. For the default tolerance, use 0 (zero). 
An approximation of a sphere sweep using a blob of spheres, with a blob field that varies in proportion to the sphere sweep radii.
Formal Parameter  Type  Description 

Type 
float  The spline type 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Res 
float  The number of sphere components between each pair of adjacent spline control points 
Field 
float  The blob field radius, in relation to the sphere radii. For example, a value of 2 results in a field radius twice the size of each sphere radius. 
Use_Sturm 
float/Boolean  Whether or not to use the slower, but more accurate Sturmian root solver. 
An approximation of a sphere sweep using a blob of spheres, with a constant blob field margin.
Formal Parameter  Type  Description 

Type 
float  The spline type 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Res 
float  The number of sphere components between each pair of adjacent spline control points 
Margin 
float  The blob field beyond the sphere radius.
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 
float/Boolean  Whether or not to use the slower, but more accurate Sturmian root solver. 
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 intersection or difference, SphereSweep_Approx()
renders faster with the same results.
Formal Parameter  Type  Description 

Type 
float  The spline type 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Res 
float  The number of segments between each pair of adjacent spline control points 
Use_merge 
float/Boolean  Whether or not to use a CSG merge. In general, pass yes if the object is to be transparent, no otherwise. 
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.
Formal Parameter  Type  Description 

Type 
float  The spline type 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Res 
float  The number of segments between each pair of adjacent spline control points 
A wrapper for the regular, bona fide sphere_sweep
primitive. 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 can use this macro to create a sphere_sweep
object from those arrays.
Formal Parameter  Type  Description 

Type 
float  The spline type. Only those spline types supported natively by POVRay’s sphere_sweep primitive can be used (SSWP_B_SPLINE , SSWP_CUBIC_SPLINE , and SSWP_LINEAR_SPLINE ). 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Tolerance 
float  The depth tolerance, as described in the sphere_sweep documentation. For the default tolerance, use 0 (zero). 
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 intersection or difference, SphereSweep_Approx()
renders faster with the same results.
Formal Parameter  Type  Description 

Type 
float  The spline type 
pv_Points 
array of point vectors  The spline control points 
Radii 
array of floats  The sphere radii corresponding to the spline control points 
Res 
float  The number of segments between each pair of adjacent spline control points 
As a convenience for facilitating continuity between cubic 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 using spline type SSWP_BEZIER_SPLINE
; or its elements may be used to construct a Bézier or prism
primitive. Optionally, the points may be written to a file.
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.
The demo scene spheresweep_cockpit.pov
demonstrates how to use this macro, and writes its output to the message window when rendered.
Formal Parameter  Type  Description 

v_Ctrls 
array[][3] of vectors  The array of points and vectors. This argument is input only and is not altered. 
s_File 
string  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 
float  The dimension size of the points to be written to the file 
Places 
float  The number of decimal places to be written 
Converts spline control points and radii in PointArrays format to SphereSweep format.
Formal Parameter  Type  Description 

paPts 
array of vectors (input only)  The array of spline control points in PointArrays format 
Radius 
float (input only)  The radius of the sphere sweep, or 0 if the radii are in the t components of paPts 
sswpPts 
array of 3D point vectors (output only)  The converted spline control points, which can then be passed to SphereSweep macros 
Radii 
array of floats (output only)  The converted radii, which can then be passed to SphereSweep macros 
Converts spline control points and radii from SphereSweep format to PointArrays format.
Formal Parameter  Type  Description 

sswpPts 
array of point vectors (input only)  The array of spline control points in SphereSweep format 
Radii 
array of floats (input only)  The array of radii in SphereSweep format 
paPts 
array of 3D or 4D vectors (output only)  The converted points, which can then be passed to PointArrays macros 
Radius 
float (output only)  A converted radius, which can then be passed to PointArrays macros 
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 blobrelated functions are available from the Object Collection module RoundEdge.
Note: In order to avoid a POVRay namespace scope feature, the function arguments in spheresweep.inc
begin with “sswp_P
” followed by a digit and an underscore. In this user manual, this prefix is omitted for clarity.
Formal Parameter  Type  Description 

RSurface 
float  The desired surface radius of the blob component 
RField 
float  The field radius of the component 
Returns a onedimensional array that is a copy of a subrange of another onedimensional array.
Formal Parameter  Type  Description 

Array 
array  The array to be copied 
Start 
float  The index of the first element to be copied 
End 
float  The index of the last element to be copied 
Start
or End
is out of range, they will be clipped to the size of the array, and a warning will be issued.
End
is less than Start
, a warning will be issued, and the contents of the returned array will be undefined. Accessing it will probably cause a fatal parse error.
Identifier  Type  Description  Value 

SPHERESWEEP_VERSION 
float  The SphereSweep version, in case the scene file needs that information.  2.0 
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.
sphere_sweep
objects based on Bsplines or cubic splines are prone to artifacts.
sphere_sweep
objects based on Bsplines or cubic splines may show artifacts when used in a CSG intersection or difference.
sphere_sweep
objects based on Bsplines or cubic splines may show discs at the end caps.
sphere_sweep
object is differenced from another object. Manual bounding would be the obvious fix, but there are undocumented circumstances in which manual bounds are lost.
For Bsplines and cubic splines, the following alternatives are free of tracing artifacts (although banding artifacts may appear if the value of Res
is too low):
SphereSweep_Union()
for opaque objects,
SphereSweep_Approx()
for opaque objects in a CSG intersection or difference, and
SphereSweep_Approx()
for transparent objects.
These observations are not hard and fast rules. All timing tests were done using POVRay 3.7.
SphereSweep_Union()
(with Res
= 1) is faster than the equivalent opaque sphere_sweep { linear_spline }
, unless a CSG intersection or difference is performed.
sphere_sweep { linear_spline }
is faster than the equivalent transparent linear SphereSweep_Merge()
.
SphereSweep_Approx()
, with a reasonable value for Res
, is slower than the equivalent straightforward sphere_sweep
, and less accurate. (The original version of this documentation said that SphereSweep_Approx()
is slightly faster, but my old records and new tests both show otherwise.) Sufficiently low values for Res
will yield faster renders than the straightforward sphere_sweep
, at the risk of revealing the individual segments.
SphereSweep_Union()
is much faster than the equivalent straightforward sphere_sweep
or SphereSweep_Approx()
, though less accurate than the straightforward sphere_sweep
.
SphereSweep_Union()
. SphereSweep_Approx()
should be used in these cases.
SphereSweep_Approx()
is faster than the equivalent straightforward sphere_sweep
, though less accurate.
SphereSweep_Merge()
, and the equivalent SphereSweep_CSG()
with Use_merge = yes
, appear to be slower in most or all cases than the alternatives, and are never more accurate. They may be less prone to artifacts, however; the demo scene spheresweep_lanes.pov
illustrates one such scenario. Another rationale for using SphereSweep_Merge()
is that the CSG merge operation is not recommended with the sphere_sweep
primitive; however, I have not witnessed the problem described in the POVRay documentation.
SphereSweep_Merge()
and a transparent SphereSweep_Approx()
: when using a Bézier spline with disjointed segments, and one disjointed segment intersects another, SphereSweep_Approx()
will render the internal surfaces. If you wish to take advantage of SphereSweep_Approx()
’s shorter rendering times in such a scenario, you will need to use a merge of separate SphereSweep_Approx()
objects.
Version  Date  Notes 

1.0  2013 July 22 

1.1  2015 August 28 

1.2  2015 September 11 

2.0  2020 September 9 
