TiltedTorus 3.0.1 User Manual

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

Abstract

[Thumbnail which links to a demo image] TiltedTorus defines tori that are scaled in the polar (y) direction, then rotated about their circular axis. A toroid lathe is included for fast renders, and an isosurface function is defined for toroids that can be deformed with other functions or blobbed with other shapes.

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
tiltedtorus.html The user manual (this document)
tiltedtorus.inc The TiltedTorus software
tiltedtorus.pov A demonstration scene description file
tiltedtorus.jpg Sample output images
tiltedtorus_thumbnail.jpg
tiltedtorus_fign.jpg Illustrations of various parameters, where the italicized n represents a decimal digit (6 images)
Administrative Files
File Description
READMEnnnnnn.html Important information about using the POV-Ray Object Collection
tiltedtorus_description.txt A brief description of TiltedTorus
tiltedtorus_keywords.txt A list of keywords
tiltedtorus_prereqs.txt Prerequisites (empty file)
tiltedtorus.css Administrative files
cc-LGPL-a.png
Versionnnnnnn.js

Note: The file tiltedtorus_cc-lgpl.png is no longer used.

Table of contents

Prerequisites

TiltedTorus requires POV-Ray version 3.5 or later.

Namespace Compliance

All file names in this module and all global and local identifiers defined in tiltedtorus.inc comply fully with the Object Collection naming standards, as revised August 2008 and proposed August 2012. The reserved prefix for this module is “tiltedtorus,” including any uppercase and lowercase variants. To avoid conflicts, do not introduce into your scene description file any identifiers with this name, or any identifiers that start with this prefix plus an underscore.

The standard include files functions.inc and transforms.inc are used by tiltedtorus.inc. The identifier View_POV_Include_Stack from the standard include file debug.inc is referenced by tiltedtorus.inc, although debug.inc itself is not used.

Usage

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

#include "tiltedtorus.inc"

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

Table of contents

Functions and Macros

TiltedTorus_fn (x, y, z, RMajor, rMinor, yScale, Tilt)

An isosurface function for a “tilted” torus. Consistent with the POV-Ray torus primitive, the toroid is oriented in the x-z plane.

Arguments

Note: In order to avoid a POV-Ray namespace scope feature, the function arguments (other than x, y, and z) in tiltedtorus.inc begin with “TiltedTorus_P” followed by a digit and an underscore. In this user manual, this prefix is omitted for clarity.

Formal Parameter Type Description
x, y, z float The coordinates of the point to be evaluated.
RMajor float The major radius of the torus.
rMinor float The minor radius of the torus.
yScale float The polar (vertical, or y) scaling factor.
Tilt float The angle by which to rotate the torus. Positive values rotate the top outwards; negative values rotate the top inwards.

Table of contents

TiltedTorus_Container_v (RMajor, rMinor, yScale, Tilt)

Returns a vector that is the half-dimensions of a box that is sufficient to contain the toroid. It may be used for the isosurface container.

Arguments

Formal Parameter Type Description
RMajor float The major radius of the torus.
rMinor float The minor radius of the torus.
yScale float The polar (vertical, or y) scaling factor.
Tilt float The angle by which to rotate the torus.

Example

isosurface
{ function { TiltedTorus_fn (x, y, z, 4, 1, 2, -45) }
  contained_by
  { box
    { -TiltedTorus_Container_v (4, 1, 2, -45),
      TiltedTorus_Container_v (4, 1, 2, -45)
    }
  }
}

Table of contents

TiltedTorus_Lathed (RMajor, rMinor, yScale, Tilt, Sturm)

A “tilted” torus, implemented as a lathe. Consistent with the POV-Ray torus primitive, the toroid is oriented in the x-z plane. This object can take a uv-mapped texture.

Arguments

Formal Parameter Type Description
RMajor float The major radius of the torus.
rMinor float The minor radius of the torus.
yScale float The polar (vertical, or y) scaling factor.
Tilt float The angle by which to rotate the torus. Positive values rotate the top outwards; negative values rotate the top inwards.
Sturm float/Boolean If true, then the slower, but more accurate Sturmian root solver will be used. If the object renders with artifacts when false is used for this argument, then use true instead.

Table of contents

Examples

[Lathe render, yScale = 1, Tilt = 0] [Lathe render, yScale = 2, Tilt = 15] [Lathe render, yScale = 3, Tilt = -45] [Isosurface render, yScale = 2, Tilt = 0] [Isosurface render, yScale = 2, Tilt = 45] [Isosurface render, yScale = 2, Tilt = -45]

Table of contents

Other Identifiers

Reference Identifier

Identifier Type Description Value
TILTEDTORUS_VERSION float The TiltedTorus version, in case the scene file needs that information. 3.01

Obsolete Identifiers

The flollowing identifiers were introduced in a previous version of TiltedTorus, but are no longer recommended. They are retained for backwards compatibility.

Internal Identifiers

Any identifiers in tiltedtorus.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

About TiltedTorus

Copyright © 2012 – 2019 Richard Callwood III. Some rights reserved. Licensed under the Creative Commons-GNU Lesser General Public License.

This shape was requested in povray.general, and I felt up to the challenge.

Object Collection Categories

Change Log

Version Date Notes
1.0 2012 July 21
  • Created.
2.0 2014 October 9
  • A lathe version is added.
  • The container macro now accommodates polar (y) scaling factors less than one.
2.0a 2014 November 7
  • Corrections are made to the user manual.
3.0 2016 April 2
  • A lathe macro is added which uses a Sturm argument rather than a global parameter.
  • The old lathe macro is deprecated.
3.0.1 2019 April 1
  • The message to the debug stream verifying that tiltedtorus.inc is included is suppressed by default.

Table of contents