README:
			PUBLIC CONTRIBUTIONS

This directory is for public submission and consumption of Radiance
models and software.  If you have something new to contribute to this
archive, please let us know first by writing to greg@hobbes.lbl.gov.
Even if you are a regular contributor, please keep us informed of any
important updates.  The Radiance mailing list, ray@hobbes.lbl.gov, is
an ideal way to do this.

Here is the current list of contribution catagories.  For a better
explanation of a directory's contents, please check the README
file therein.

digest		- Back issues of the Radiance Digest
generators	- Programs for generating specialized objects & shapes
iesdata		- IES format luminaire data
libraries	- Libraries of patterns, textures, fonts, etc.
mac		- MacIntosh applications and utilities (for Radiance)
models		- Complete Radiance scene descriptions
objects		- Objects for including in Radiance scenes
pics		- Pictures directory (outgoing only)
ports		- Patches and utilities for non-UNIX systems
programs	- Miscellaneous programs and utilities
tests		- Test scenes for validating global illumination programs
translators	- CAD file translators and image format converters
xfer		- Temporary transfer directory

generators/README:
			GENERATOR PROGRAMS

A generator program creates a Radiance description of some special
shape or object type.  Such a program should always write a legal
Radiance scene description to the standard output.  Usually, the
description will be geometry only, and will assume the object generated
to be of a single material type given on the command line.  This makes
it easy to use the generator program as an escape command within a
Radiance scene description file.

A typical example of a generator program is genbox.  Genbox takes as
arguments the name of the material, the name of the object, and the
width, depth and height of the box.  The box is always created in the
positive octant and must be moved to the desired location with xform.
This is preferable to adding complexity to the genbox program itself.
As an example, genbox can be used to create a 4x3x5 house out of
the material "straw" at (-1,15,3) by including the following line in
the scene description file:

	!genbox straw house 4 3 5 | xform -t -1 15 3

All contributions should be stored as compressed tar files that when
unpacked will create a directory with the program's name containing
a Makefile, the necessary source modules, and a manual page.  Please
use the file genbox.tar.Z as a model.

iesdata/README:
			IESDATA

This directory contains luminaire output data in standard IES format.
These files can be converted to Radiance scene files using ies2rad.
Since ies2rad provides a number of options for the translation, it
is a good idea to keep the original IES files around.  Also, we
welcome any IES files you might want to add to our collection.
As you can see, our selection could use some fresh blood.

emco.tar.Z		- EMCO street lights
gardco.tar.Z		- GARDCO street lights
headlight.tar.Z		- A few headlights with wide distributions
ies.tar.Z		- The standard IES luminaire set

libraries/README:
			LIBRARIES

This directory contains favorite library files (a.k.a. auxiliary files)
used by Radiance, including procedural patterns and textures, scanned
patterns, fonts, compiled objects and so on.

Each file in this directory is a compressed tar file with the name of
the person or entity who made the contribution.  These files should
unpack to create a directory by the same name containing the various
submission that person or entity has to offer.  There should also be
included a README file saying what each file is.

When naming auxiliary files, the following conventions should be
followed as closely as possible.  Files with the ".cal" suffix specify
procedural patterns, textures and coordinate mappings.  Files with the
".fnt" suffix are font descriptions.  Files with the ".oct" suffix are
compiled scene descriptions for use in instances.  Files with the
".pic" suffix are images for patterns.  Pictures for use as patterns
are normalized to a value of 1 rather than the more usual .5, and must
be displayed with the -e -1 option.  This is so the material
reflectance given in the scene description holds true.  The exception
to this is pictures that are not meant to be used as repeated patterns,
but instead as paintings or pictures to hang on the wall.

If you wish to make a contribution to this directory, please look at
the tar file gjward.tar.Z as a model.

models/README:
			MODELS

This directory contains complete Radiance scene descriptions with
the necessary makefiles for rebuilding the octrees and rendering
the scene with rview from a good viewpoint.  These models are
stored as compressed tar files that unpack to a directory with
all the required input and auxiliary files.

Here is a list of models currently offered:

bath.tar.Z	- Modest bathroom model by Greg Ward
conf.tar.Z	- LBL conference room by Anat Grynberg and Greg Ward
cubspace.tar.Z	- Cubicle office space by Anat Grynberg and Greg Ward
podlife.tar.Z	- Whale sculpture by Cindy Larson and Greg Ward
soda.tar.Z	- Ice cream store by Greg Ward

If you are making a submission, please do what is necessary to make
the first paragraph true.  Please do not include any octrees or large
images of your model, since they require too much storage space.  You may
follow the example in podlife.tar.Z.

objects/README:
			OBJECTS

I have the following suggestions for object coordinates, which should
be made more specific with overall dimensions in a comment at the top
of each file:

Furniture:		Units = meters
			[The following is described looking from "back"]
			(0,0,0) located at bottom back left corner
			X-axis directed towards "right"
			Y-axis directed towards "front"
			Z-axis directed up

Knick-knacks:		Units = meters or centimeters
			Orient the same as furniture except (0,0,0) can be
			at center of rest point (ie. bottom) if object has
			high degree of radial symmetry (eg. a vase or cup).

Fixtures:		Units = meters
			[Present right-handed version only, ie. hinge
			on right means pull fixture towards you on left]
			(0,0,0) at lowest hinge or mount point if there is one,
				highest mount point if it is a ceiling fixture
			X-axis in plane of fixture, towards handle side if one
			Y-axis out of plane
			Z-axis up

Buildings:		Units = meters
			(0,0,0) located at the ground level of SW corner
			X-axis directed towards "East"
			Y-axis directed towards "North"
			Z-axis directed up

Plants:			Units = meters
			(0,0,0) located where ground meets plant (ie. the root)
			Y-axis directed "North" for phototropic plants
			Z-axis directed up

People (standing):	Units = meters
			(0,0,0) located at ground under center of gravity
			X-axis points to person's right
			Y-axis points in person's forward direction
			Z-axis directed up

People (sitting):	Units = meters
			(0,0,0) located at rump under center of gravity
			X-axis points to person's right
			Y-axis points in person's forward direction
			Z-axis directed up

People (laying):	Units = meters
			(0,0,0) located at back of the head
			X-axis points to person's right (left if prone)
			Y-axis points towards feet
			Z-axis directed up

Animals (excl. people)	Units = meters
			(0,0,0) located at rear (ground level if land animal)
			X-axis pointing to animal's right
			Y-axis to animals front
			Z-axis directed up

Objects should be collected in compressed tar files, one such file per
contributor.  It would be too messy to have one tar file for each object,
since each person might contribute several objects, and everyone has
an object called "chair".

ports/README:
			PORTS

This directory is for ports of Radiance to non-standard or
non-UNIX systems that require significant modifications.
It is also a good place to put additional graphics drivers
and other hardware-specific code supplements.

If you have ported Radiance to a specific architecture that
is not listed here, please make a new directory for your
machine and place your patches and comments in it.  Please
do not deposit large collections of uncompressed executables,
since hobbes does not have a real wealth of disk space.
After leaving your files, please make an announcement to the
ray@hobbes.lbl.gov mailing list to let folks know about it.

Currently in this directory:

amiga		- Commodore AmigaOS patches and utilities

programs/README:
			PROGRAMS

This directory contains contributed Radiance programs that don't
really fit into the generator or input/output translator categories.

So far, we have the following contributions:

preview.tar.Z	- An X11 previewer for Radiance models by Sumanta Pattanaik

These are all compressed tar files that unpack to a directory with the
necessary Makefile included.  Please do not redistribute any of these
programs without getting prior permission from the author(s).

tests/obstructed/diffuse/rgb/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The two smaller walls at either end of the room are colored red and
blue.  The wall at x==0 has an (r,g,b) reflectance of (1,.29,.29).
The wall at x==10 has an (r,g,b) reflectance of (.44,.44,1).  All
other surfaces are diffuse grey.

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The coordinates are measured
from the origin at one corner of the room.  The longer wall is aligned
with the x-axis, and the z-axis points up.

This room contains two vertical partitions, each full height (3).
The first runs from (x,y) = (3,3) to (3,6).  The second runs from
(x,y) = (7,0) to (7,3).  Both partions are .1 thick in x and have
the same reflectance properties as the other grey walls.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/obstructed/diffuse/grey/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The coordinates are measured
from the origin at one corner of the room.  The longer wall is aligned
with the x-axis, and the z-axis points up.

This room contains two vertical partitions, each full height (3).
The first runs from (x,y) = (3,3) to (3,6).  The second runs from
(x,y) = (7,0) to (7,3).  Both partions are .1 thick in x and have
the same reflectance properties as the other grey walls.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/obstructed/specular/rgb/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The two smaller walls at either end of the room are colored red and
blue.  The wall at x==0 has an (r,g,b) reflectance of (1,.29,.29).
The wall at x==10 has an (r,g,b) reflectance of (.44,.44,1).  All
other surfaces are diffuse grey.

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The coordinates are measured
from the origin at one corner of the room.  The longer wall is aligned
with the x-axis, and the z-axis points up.

This room contains two vertical partitions, each full height (3).
The first runs from (x,y) = (3,3) to (3,6).  The second runs from
(x,y) = (7,0) to (7,3).  Both partions are .1 thick in x and have
the same reflectance properties as the other grey walls.

There are three versions of this room.  The first version, room1, has
a single ideally specular wall surface (reflectance = 75%) at y==0.
The second version, room2, has two specular wall surfaces, one at y==0
and the other at x==0.  Since these walls are at right angles, there
can be at most two specular reflections before striking a diffuse surface.
The third version of the room, room3, also has two specular wall surfaces,
one at y==0 and the other at y==6.  Since these surfaces face each other,
there is no real limit to the number of specular interreflections.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/obstructed/specular/grey/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The coordinates are measured
from the origin at one corner of the room.  The longer wall is aligned
with the x-axis, and the z-axis points up.

This room contains two vertical partitions, each full height (3).
The first runs from (x,y) = (3,3) to (3,6).  The second runs from
(x,y) = (7,0) to (7,3).  Both partions are .1 thick in x and have
the same reflectance properties as the other grey walls.

There are three versions of this room.  The first version, room1, has
a single ideally specular wall surface (reflectance = 75%) at y==0.
The second version, room2, has two specular wall surfaces, one at y==0
and the other at x==0.  Since these walls are at right angles, there
can be at most two specular reflections before striking a diffuse surface.
The third version of the room, room3, also has two specular wall surfaces,
one at y==0 and the other at y==6.  Since these surfaces face each other,
there is no real limit to the number of specular interreflections.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/empty/diffuse/rgb/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The two smaller walls at either end of the room are colored red and
blue.  The wall at x==0 has an (r,g,b) reflectance of (1,.29,.29).
The wall at x==10 has an (r,g,b) reflectance of (.44,.44,1).  All
other surfaces are diffuse grey.

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The given coordinates are
measured from the origin at one corner of the room.  The longer wall is
aligned with the x-axis, and the z-axis points up.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/empty/specular/rgb/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The two smaller walls at either end of the room are colored red and
blue.  The wall at x==0 has an (r,g,b) reflectance of (1,.29,.29).
The wall at x==10 has an (r,g,b) reflectance of (.44,.44,1).  All
other surfaces are diffuse grey.

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The given coordinates are
measured from the origin at one corner of the room.  The longer wall is
aligned with the x-axis, and the z-axis points up.

There are three versions of this room.  The first version, room1, has
a single ideally specular wall surface (reflectance = 75%) at y==0.
The second version, room2, has two specular wall surfaces, one at y==0
and the other at x==0.  Since these walls are at right angles, there
can be at most two specular reflections before striking a diffuse surface.
The third version of the room, room3, also has two specular wall surfaces,
one at y==0 and the other at y==6.  Since these surfaces face each other,
there is no real limit to the number of specular interreflections.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/empty/specular/grey/README:
The basic space is a 10 by 6 by 3 rectangular room (length units are
irrelevant, but think of them as meters if you like).  At the center
of the ceiling is a single square fixture that measures .5 on a side.
The grey emittances and reflectances are as follows:

	Surface		Emittance (w/m^2)	Reflectance (%)
	=======		=================	===============
	Source		31.416			0
	Ceiling		0			70
	Walls		0			50
	Floor		0			30

The calculation points on the floor and ceiling are separated by .5 in
each dimension, starting .25 from the edge.  Note that this means they
are not symmetrical about the center.  The given coordinates are
measured from the origin at one corner of the room.  The longer wall is
aligned with the x-axis, and the z-axis points up.

There are three versions of this room.  The first version, room1, has
a single ideally specular wall surface (reflectance = 75%) at y==0.
The second version, room2, has two specular wall surfaces, one at y==0
and the other at x==0.  Since these walls are at right angles, there
can be at most two specular reflections before striking a diffuse surface.
The third version of the room, room3, also has two specular wall surfaces,
one at y==0 and the other at y==6.  Since these surfaces face each other,
there is no real limit to the number of specular interreflections.

Results are stored in three forms.  The first is the raw output of the
Radiance rtrace(1) command, which is stored in a file ending in .res.
This is in the form x y z r g b for each point on the floor and each
point on the ceiling.  The second form is a plot file (ending in .plt)
for bgraph(1) and contains one curve for each Y position.  The third
form is a PostScript version of the plot files, ending in the .ps suffix.

All results are given in units of radiance (watts/sr/m^2).  To convert
to radiosity (w/m^2), simply multiply by pi and divide by the diffuse
reflectance of the surface (.7 for the ceiling, .3 for the floor).  I
prefer to use radiance not because that's the name I chose for my software
but because radiance is consistent with any type of surface reflectance.
It does not make sense to talk about the radiosity of a non-Lambertian
surface, for example, whereas both radiance and irradiance make perfect
sense.

tests/README:
			TESTS

This directory contains some test scenes and results for checking
calculations against other people's programs.  The subdirectories
are broken down according to model type as follows:

	empty/*/*	- Environments without obstructions
	obstructed/*/*	- Obstructed environments
	*/diffuse/*	- Diffuse surfaces only
	*/specular/*	- Surfaces may have some (ideal) specularity
	*/brdf/*	- Surfaces may have arbitrary BRDF's
	*/*/grey	- Grey surfaces only
	*/*/rgb		- Surfaces with RGB color
	*/*/spectral	- Surfaces with > 3 spectral samples

All models and files should be put in the bottom set of directories.
Solutions should be given in human-readable text form, and should
describe very thoroughly how they were obtained.  Please name your
files uniquely using some abbreviation of your name or group, so
we don't get name collisions when everyone starts dumping their
results into the obstructed/brdf/spectral directory (ha, ha).

There are currently Radiance-generated results in the following directories:

empty/diffuse/grey
empty/diffuse/rgb
empty/specular/grey
empty/specular/rgb
obstructed/diffuse/grey
obstructed/diffuse/rgb
obstructed/specular/grey
obstructed/specular/rgb

Most of the directories contain README files explaining their contents.
The empty/diffuse/grey directory contains results not only from Radiance,
but also from Holly Rushmeier and sometimes Sumanta Pattanaik.

There may be a compressed tar file in this directory with the contents of
all subdirectories as of a specific date.  For example, 91-10-28.tar.Z
would contain the contents of this directory and all its subdirectories
as of October 28, 1991.

translators/README:
			TRANSLATORS

This directory contains contributed CAD translators and image file
converters for going to and from Radiance.  Most of the programs should
be here as compressed tar files that unpack to create a directory with
the appropriate Makefile and manual page(s).

By convention, CAD format translators are named something like *2rad,
and usually do not perform the reverse conversion from Radiance models
to the CAD system.  Image file converters, on the other hand, should
provide a '-r' option to go from the foreign image format to a Radiance
floating point pictures.  The convention for image converter names is ra_*.

The following translators have been contributed so far:

dxf2rad.lisp	- An AutoLISP DXF translator by Robert Amor [uncompressed]
pict.tar.Z	- A translator from Radiance to Macintosh PICT

If you are planning to write a CAD format translator for Radiance, please
consult the README file in the ray/src/cv directory of the standard
Radiance distribution.

If you wish to write an image converter, please avail yourself of the
Radiance scanline color manipulation routines in ray/src/px:  color.h,
resolu.h, color.c, colrops.c, header.c and resolu.c.  You may use start
from the ra_skel.c example converter.  If you are converting to 8-bit
color, you may also want to use the routines in ciq.c, cut.c and
closest.c.  You can follow ra_pr as an example of 8-bit color
conversion.  If you are converting to some raw image format, you should
check that pvalue doesn't do the conversion already.