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. Also included is an alternate interface to the actual sphere_sweep
object.
The control points and radii are specified in arrays.
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_cockpit.pov |
Demonstration scene description files |
spheresweep_infinity.pov |
|
spheresweep_lanes.pov |
|
README nnnnnn.html |
Important information about using the Object Collection |
Other Files | |
File | Description |
spheresweep.css |
A file used by the user manual |
spheresweep_blob_field.jpg |
Illustrations for the user manual |
spheresweep_blob_margin.jpg |
|
spheresweep_icon_diff.png |
|
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 |
Version nnnnnn.js |
Include this file once prior to using any of the macros:
#include "spheresweep.inc"
Including the file more than once is unnecessary, but harmless.
If any of the object macros other than SphereSweep_Native()
are used, POV-Ray will issue a warning that the experimental feature spline is used. This is normal and expected.
Requires POV-Ray version 3.5 or later.
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
.
These values may be used as the Type
argument:
SSWP_B_SPLINE
SSWP_CUBIC_SPLINE
SSWP_LINEAR_SPLINE
SSWP_NATURAL_SPLINE
SSWP_QUADRATIC_SPLINE
Not all spline types can be used with all macros. This table gives a summary of availability:
Macro | B-Spline | Bézier Spline | Cubic Spline | Linear Spline | Natural Spline | Quadratic Spline |
---|---|---|---|---|---|---|
SphereSweep_Approx |
no | no | YES | YES | YES | YES |
SphereSweep_Blob_field |
no | no | YES | YES | YES | YES |
SphereSweep_Blob_margin |
no | no | YES | YES | YES | YES |
SphereSweep_CSG |
no | no | YES | YES | YES | YES |
SphereSweep_Merge |
no | no | YES | YES | YES | YES |
SphereSweep_Native |
YES | no | YES | YES | no | no |
SphereSweep_Union |
no | no | YES | YES | YES | YES |
The elements of the v_Points
array will be converted to 3-D vectors. A flat object can be defined in the x-y plane with an array of 2-D vectors.
If the Radii
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.
A sphere_sweep
object 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).
Type
:
v_Points
:
Radii
:
Res
:
Tolerance
:
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.
Type
:
v_Points
:
Radii
:
Res
:
Field
:
Use_Sturm
:
An approximation of a sphere sweep using a blob of spheres, with a constant blob field margin.
Type
:
v_Points
:
Radii
:
Res
:
Margin
:
Margin
is 0.5 and a sphere’s radius is 2.0, then the field radius will be 2.5.
Use_Sturm
:
An approximation of a sphere sweep using a CSG merge or union of linear segments. Note that for transparent objects, SphereSweep_Approx()
renders faster with the same results.
Type
:
v_Points
:
Radii
:
Res
:
Use_merge
:
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.
Type
:
v_Points
:
Radii
:
Res
:
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.
Type
:
sphere_sweep
primitive can be used (SSWP_B_SPLINE
, SSWP_CUBIC_SPLINE
, and SSWP_LINEAR_SPLINE
).
v_Points
:
Radii
:
Tolerance
:
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.
Type
:
v_Points
:
Radii
:
Res
:
Returns a one-dimensional array that is a copy of a subrange of another one-dimensional array.
Array
:
Start
:
End
:
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.
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.
Note: In spheresweep.inc
, the function arguments are prefixed with “sswp_P
n_
” in order to avoid a POV-Ray namespace scope feature. These prefixes are omitted here for clarity.
RSurface
:
RField
:
Identifier | Type | Description | Value |
---|---|---|---|
SPHERESWEEP_VERSION |
float | The SphereSweep version, in case the caller needs to know. | 1.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 B-splines or cubic splines are prone to artifacts.
For cubic splines, the following alternatives are free of artifacts and faster, though less accurate:
SphereSweep_Union()
for opaque objects,
SphereSweep_Approx()
for opaque objects in a CSG intersection or difference, and
SphereSweep_Approx()
for transparent objects.
sphere_sweep
objects in POV-Ray 3.7, so upgrading is recommended. Automatic bounding remains unreliable for cubic splines, however.
sphere_sweep
objects based on B-splines or cubic splines may show discs at the end caps. For cubic splines, SphereSweep_Approx()
provides a slightly faster, artifact-free alterative, though it is less accurate. This version of the SphereSweep module does not provide a B-spline approximation.
These observations are not hard and fast rules.
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()
is slightly faster than the equivalent sphere_sweep
object, though less accurate.
SphereSweep_Union()
is much faster than the equivalent sphere_sweep
object or SphereSweep_Approx()
, though less accurate than the sphere_sweep
object.
SphereSweep_Union()
.
SphereSweep_Approx()
is faster than the equivalent sphere_sweep
object, 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
object; however, I have not seen the described problem.
Version | Date | Notes |
---|---|---|
1.0 | July 22, 2013 |
|