CoffeeMug 2.0 User Manual

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

Abstract

[Thumbnail which links to a montage of larger demo images] Some objects, though not used directly in office work, are nevertheless indispensable for the efficient functioning of the office. This module defines macros for a coffee mug and a beverage object to fill it.


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
coffeemug.html The user manual (this document)
coffeemug.inc The CoffeeMug software
coffeemug.jpg Sample output
coffeemug.pov An example scene description file, demonstrating how to use coffeemug.inc.
coffeemug_map.jpg An image used by the example scene description file
READMEnnnnnn.html Important information about using the POV-Ray Object Collection
Other Files
File Description
coffeemug.css A file used by the user manual
coffeemug_fig1.jpg Illustrations for the user manual
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 files
Versionnnnnnn.js

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

Table of contents


Prerequisites

CoffeeMug requires POV-Ray version 3.5 or later.

Namespace Compliance

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

Usage

Include this file once prior to using the macros:

#include "coffeemug.inc"

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

Table of contents


Macros

CoffeeMug_Mug (Radius, Capacity, Units, Use_merge)

An untextured coffee mug, with the bottom center of the mug at the origin, and the handle pointing in the negative z direction.

Arguments

Radius:
The outer radius of the mug.
Capacity:
The height or net volume of the mug. The 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.

Note: CoffeeMug_Mug() calls macro CoffeeMug_Detail(), supplying its own automatically calculated arguments. If the mug is very short, the calculated handle dimensions will trigger a warning from CoffeeMug_Detail().

Table of contents

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

An untextured coffee mug with more user control over the dimensions. The bottom center of the mug is at the origin, and the handle points in the negative z direction.

Arguments

Radius:
The outer radius of the mug.
Wall:
The thickness of the wall.
Capacity:
The height or net volume of the mug. The unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
v_Handle:
The dimensions of the handle.
Handle_space:
The horizontal 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.

Table of contents

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

A beverage pre-sculpted to fit the coffee mug. The object is untextured, so you can create and apply your own materials for black coffee, 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. Carbonation for rum and Coke is available separately from the Object Collection’s bubble module.

Due to some technical considerations, no beverage materials are defined in coffeemug.inc. However, the example scene coffeemug.pov demonstrates an example material for café au lait, which you can copy and modify to your taste.

Arguments

Radius:
The outer radius of the mug for which the beverage is intended.
Wall:
The thickness of the mug’s wall. Use 0 if the mug is created with CoffeeMug_Mug().
Capacity:
The height or volume of the beverage. The unit of measure is determined by the Units argument.

Note: The meniscus and the curvature of the floor of the mug are not considered in the volume-to-height calculation.

Units:
Determines the units of measure.

Note: If set to COFFEEMUG_HEIGHT or MUG_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.

Table of contents


CoffeeMug_Height (Radius, Capacity, Units)

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

Arguments

Radius:
The radius of the cylinder.
Capacity:
The height or volume of the cylinder. The unit of measure is determined by the Units argument.
Units:
Determines the units of measure.

Table of contents


CoffeeMug_Stack_height (Radius, Wall, Capacity, Units)

Returns the height a mug is raised when stacked on top of another.

Arguments

Radius:
The radius of the mugs.
Wall:
The thickness of the mugs’ walls. Use 0 if the mugs are created with CoffeeMug_Mug().
Capacity:
The height or volume of the bottom mug. The unit of measure is determined by the Units argument.
Units:
Determines the units of measure.

Example

CoffeeMug_Mug (3.75, 300, MUG_CM, no)
#declare Stack = CoffeeMug_Stack_height (3.75, 0, 300, MUG_CM);
object
{ CoffeeMug_Mug (3.75, 240, MUG_CM, no)
  translate Stack * y
}
#declare Stack = Stack + CoffeeMug_Stack_height (3.75, 0, 240, MUG_CM);
object
{ CoffeeMug_Mug (3.75, 280, MUG_CM, no)
  translate Stack * y
}

Table of contents


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

Returns a cylindrical pigment, based on user-supplied pigments. A slice of the foreground pigment is taken at the x-y plane, optionally masked by an object, transformed to the middle-front of a hypothetical mug, and wrapped around the mug.

These illustrations show how the masking object is mapped to the mug. As of CoffeeMug version 2.0, pigments and textures are also mapped in the same manner.

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

Arguments

Radius:
The outer radius of the mug for which the pigment is intended.
Wall:
The thickness of the mug’s wall. Use 0 if the mug is created with CoffeeMug_Mug().
Capacity:
The height or net volume of the mug. The unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
o_Mask:
The object to be used as the pigment mask, which must be centered on the origin. Use MUG_NO_MASK if no mask is to be used.
p_Background:
The pigment to be used for the area outside the mask, including the inside and bottom of the mug. This pigment will not be cylindrically mapped or otherwise transformed.
p_Foreground:
The pigment to be mapped to the mug, which must be centered on the origin.

Example

#declare P = pigment
{ image_map { png "bumpmap_" }
  translate -0.5 // Center the image.
  scale <3.2, 2, 1>
}
object
{ CoffeeMug_Mug (1.5, 3.5, MUG_HEIGHT, no)
  CoffeeMug_Pigment
  ( 1.5, 0, 3.5, MUG_HEIGHT,
    box { -<1.6, 1, 1>, <1.6, 1, 1> }, rgb <0, 1, 1>, P
  )
}

Table of contents


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

Returns a cylindrical texture, based on user-supplied textures. A slice of the foreground texture is taken at the x-y plane, optionally masked by an object, transformed to the middle-front of a hypothetical mug, and wrapped around the mug, as shown in these illustrations.

Arguments

Radius:
The outer radius of the mug for which the texture is intended.
Wall:
The thickness of the mug’s wall. Use 0 if the mug is created with CoffeeMug_Mug().
Capacity:
The height or net volume of the mug. The unit of measure is determined by the Units argument.
Units:
Determines the units of measure.
o_Mask:
The object to be used as the texture mask, which must be centered on the origin. Use MUG_NO_MASK if no mask is to be used.
p_Background:
The texture to used for the area outside the mask, including the inside and bottom of the mug. This texture will not be cylindrically mapped or otherwise transformed.
p_Foreground:
The texture to be mapped to the mug, which must be centered on the origin.

Table of contents


CoffeeMug_Wrap (Radius)

Transforms a pigment, a normal, or a texture map such that it wraps around a hypothetical cylinder. The pattern is transformed such that the x-y plane is rotated to the +z side of a cylinder centered on the origin, then wrapped around it, in the same manner as the object shown in these illustrations.

Argument

Radius:
The radius of the cylinder around which the pattern is to be wrapped.

Example

cylinder
{ -y, y, 1.5
  pigment
  { checker scale 0.5
    CoffeeMug_Wrap (1.5)
  }
}

Table of contents


Units of Measure

Code Alternate Code Linear POV-Unit Assumed Capacity Unit
COFFEEMUG_INCH MUG_INCH Inches Fluid ounces
COFFEEMUG_CM MUG_CM Centimeters Milliliters
COFFEEMUG_MM MUG_MM Millimeters Milliliters
COFFEEMUG_HEIGHT MUG_HEIGHT Arbitrary The capacity argument determines the height instead of the volume

Table of contents


Other Identifiers

Global Parameters

The following parameters are used by the macro CoffeeMug_Beverage(). They may be changed at any time by the user.

Parameter Type Description Default
CoffeeMug_ConAngle float The contact angle of the meniscus, in degrees. Valid values are 0 (concave, completely wet) to 180 (convex, completely phobic). 8
CoffeeMug_rMeniscus float The radius of the meniscus curve, in millimeters. 2

Reference Identifiers

Identifier Type Description Value
COFFEEMUG_NO_MASK object This may be passed to CoffeeMug_Pigment() or CoffeeMug_Texture() as the o_Mask argument to indicate that there is no object mask.
COFFEEMUG_VERSION float The CoffeeMug version, in case the scene file needs that information. 2.0

Short Form Identifiers

With the introduction of the short prefix “mug,” many of the identifiers in CoffeeMug have been given shortened alternatives. These identifiers and their alternatives are listed in this table. (Please note that warning messages from macros will announce the longer form, regardless of which form is called from your scene file.)
Long Form Short Form
CoffeeMug_Beverage Mug_Beverage
COFFEEMUG_CM MUG_CM
CoffeeMug_Detail Mug_Detail
CoffeeMug_Height Mug_Height
COFFEEMUG_HEIGHT MUG_HEIGHT
COFFEEMUG_INCH MUG_INCH
COFFEEMUG_MM MUG_MM
CoffeeMug_Mug Mug_Mug
COFFEEMUG_NO_MASK MUG_NO_MASK
CoffeeMug_Pigment Mug_Pigment
CoffeeMug_Stack_height Mug_Stack_height
CoffeeMug_Texture Mug_Texture
CoffeeMug_Wrap Mug_Wrap

Internal Identifiers

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

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

Change Log

Version Date Notes
1.0 2008 August 7
  • The initial upload.
1.1 2008 August 8
  • Pigment and texture options are added.
1.2 2008 August 31
  • Local identifiers are renamed to comply with the August 2008 revision to the naming standards.
1.3 2013 May 20
  • Options for controlling the meniscus are added.
1.3a 2013 May 21 Same as version 1.3, but with the sample output corrected.
2.0 2015 March 05
  • Pigments and textures are cylindrically mapped, allowing for more than simple object masks.
  • A macro to compute the stacking height of a mug is added.
  • A short prefix is introduced.
  • A version identifier is added.
  • The bottom of the mug is remodeled.

Acknowledgments

Table of contents