CoffeeMug User Manual

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

Abstract

[Demo] Some objects, though not used directly in office work, are nevertheless indispensable for the efficient functioning of the office.

Contents

Overview

Downloaded Files

Key Files
File Description
coffeemug.html The user manual (this document)
coffeemug.inc The CoffeeMug software
coffeemug.jpg Sample output
coffeemug.pov An example scene file
READMEnnnnnn.html Important information that you need to know
Other Files
File Description
coffeemug.css A support file for the user manual
coffeemug_cc-lgpl.png Support illustrations for the user manual
coffeemug_fig1.jpg
coffeemug_fig4.jpg
coffeemug_fig5.jpg
coffeemug_thumbnail.jpg
coffeemug_description.txt A brief description of CoffeeMug
coffeemug_keywords.txt A list of keywords
coffeemug_prereqs.txt Prerequisites (empty file)
cc-LGPL-a.png Administrative support file
Versionnnnnnn.js Administrative support file

Contents

Usage

The file coffeemug.inc defines macros that create a coffee mug and a beverage to fill it. Include this file once prior to using the macros: 

#include "coffeemug.inc"

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

Prerequisites

None.

Name Space Compliance

All file names, global identifiers, and local identifiers comply with the Object Collection naming standards. The case-insensitive prefix for this module is “coffeemug.”

Contents

Macros

CoffeeMug_Mug (Radius, Capacity, Units, Use_merge)

An untextured coffee mug, with the handle pointing in the negative z direction.

Arguments:

Radius:
Outer radius of the mug.
Capacity:
Height or volume of the mug. Unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
Use_merge:
Whether to use a union or a merge. In general, pass yes if the mug is to be transparent, no otherwise.

Contents

CoffeeMug_Detail (Radius, Wall, Capacity, Units, Handle, Handle_space, Use_merge)

An untextured coffee mug with more user control over the dimensions. The handle points in the negative z direction.

Arguments:

Radius:
Outer radius of the mug.
Wall:
Thickness of the wall.
Capacity:
Height or volume of the mug. Unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
Handle:
Dimensions of the handle.
Handle_space:
The finger space between the handle and the wall of the mug.
Use_merge:
Whether to use a union or a merge. In general, pass yes if the mug is to be transparent, no otherwise.

Contents

CoffeeMug_Beverage (Radius, Wall, Capacity, Units, Epsilon)

A beverage pre-sculpted to fit the coffee mug. The object is untextured, allowing the user the choice of coffee black, café au lait, cocoa, tea, apple cider, Dasani®, rum and Coke®, or any of a number of other quaffs. The object will not contour to the rim of the mug, and no carbonation is provided for the rum and Coke.

Arguments:

Radius:
Outer radius of the mug.
Wall:
Thickness of the wall. Use 0.0 if the mug is created with CoffeeMug_Mug().
Capacity:
Height or volume of the beverage. Unit of measure is determined by the Units argument.
Units:
Determines the units of measure. Note: if set to COFFEEMUG_HEIGHT, the meniscus will not be modeled.
Epsilon:
A tiny value to avoid a coincident surface with the inner wall of the mug. A negative value creates a space between the liquid and the mug; a positive value intersects the mug.

Contents

CoffeeMug_Height (Radius, Capacity, Units)

Computes the height of a cylinder, given its capacity and radius.

Arguments:

Radius:
Radius of the cylinder.
Capacity:
Height or volume of the cylinder. Unit of measure is determined by the Units argument.
Units:
Determines the units of measure.

Contents

CoffeeMug_Pigment (Radius, Wall, Capacity, Units, o_Print, p_Background, p_Foreground)

Returns a cylindrically-mapped block pigment from a user-supplied object. A slice is taken at the x-y plane, transformed to the middle-front of the mug, and wrapped around the mug. The object should be centered on the origin.

Arguments:

Radius:
Outer radius of the mug.
Wall:
Thickness of the wall. Use 0.0 if the mug is created with CoffeeMug_Mug().
Capacity:
Height or volume of the beverage. Unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
o_Print:
The object to be used as the pigment pattern.
p_Background:
A background pigment.
p_Foreground:
A foreground pigment.

These illustrations show how an object is mapped to the mug.

[An object and a mug.] [How CoffeeMug_Pigment() or CoffeeMug_Texture() orients the object] [The fully textured mug.]

Contents

CoffeeMug_Texture (Radius, Wall, Capacity, Units, o_Print, t_Background, t_Foreground)

Returns a cylindrically-mapped block texture from a user-supplied object. A slice is taken at the x-y plane, transformed to the middle-front of the mug, and wrapped around the mug, as shown in these illustrations. The object should be centered on the origin.

Arguments:

Radius:
Outer radius of the mug.
Wall:
Thickness of the wall. Use 0.0 if the mug is created with CoffeeMug_Mug().
Capacity:
Height or volume of the beverage. Unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
o_Print:
The object to be used as the texture pattern.
t_Background:
A background texture.
t_Foreground:
A foreground texture.

Contents

Units of Measure

Code Linear Unit Liquid Measure (Volume)
COFFEEMUG_HEIGHT Arbitrary The capacity argument is used as the height
COFFEEMUG_INCH Inches Fluid ounces
COFFEEMUG_CM Centimeters Milliliters
COFFEEMUG_MM Millimeters Milliliters

Contents

Other Identifiers

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

Contents

About CoffeeMug

© 2008 Richard Callwood III. Some rights reserved. Licensed under the Creative Commons-GNU Lesser General Purpose License.

Change Log

Version Date Notes
1.0 August 7, 2008 Software created.
1.1 August 8, 2008 Texture options added.
1.2 August 31, 2008 Namespace compliance is extended.

User Manual (this document) updated August 31, 2008.

Acknowledgements

Coke® and Dasani® are registered trademarks of the Coca-Cola Company. No endorsement is implied.

Contents