readme.theatresys.txt

===========================================================================
TheatreSys - theatrical lighting macros for POV-Ray 
===========================================================================

Macros for realistic theatrical lighting.
	
Christopher Shake, February 2009	(cshake+pov@gmail.com)
	
Uses functions from LightSys IV by Jaime Vives Piqueres, which can be
found at http://www.ignorancia.org/t_lightsys.php


This file must be included if any part of theatresys is redistributed.

This file and all parts of TheatreSys are licensed under the
Creative Commons Attribution-Noncommercial 3.0 Unported License
http://creativecommons.org/licenses/by-nc/3.0/
===========================================================================
Background:

	After working in a student theatre on the technical crew for a few years
during high school and my undergrad work, I decided that I wanted at way
to model a full stage light rig, but being on a college budget was not able
to afford the expensive software that already does this. I turned back to
POV-Ray, which I had experimented with for a few years, and realize that
it was the perfect candidate for what I had in mind.

	I remembered a website from a while ago that had really impressed me
with the quality of renders and the attention to producing results as
realistic as possible (JVP's site www.ignorancia.org), and saw that he
had created a very good base for accurate lighting. I had tried to use it
before for my other rendering projects, but found that HDRI lighting was
far superior for what I needed then. Now I returned to LightSys and found
it the perfect option. Theatresys uses mostly CIE.inc, but includes the
fading macro from LightSys.

	While there are commercial softwares for simulating theatrical lighting,
most notably WYSIWYG from Cast Software, I wanted to both learn more
about POV-Ray and give something back to the community.

===========================================================================
What it is:

	Theatresys allows you to place a variety of commercially available
lighting instruments anywhere in your scene, and attemps to model as
accurately as possible what the real instrument does.

	Using the spectral calculations in CIE.inc (included with lightsys),
accurate colors for various lamps are modeled according to the published
color temperatures. Color gels are modeled similarly by using the spectral
data to determine the color transmitted.

	Gobos and other images can be projected with any lamp, using any image
as the pattern. Simple black+white images work like steel cutout gobos,
while full color images work like slide projectors or glass gobos.
Theoretically a range of images can be used with an animation to create a
movie projector.

	A basic backdrop and figure are provided to help you start on your scene.

===========================================================================
How to use:

	Download LightSys from www.ignorancia.org/t_lightsys.php
	
	First, #declare Global_TheatreSys_Unit = [1-5]. See theatresys.inc for
what each value means. This makes scales everything that is generated
by theatresys according to whatever you are using as your base unit.
For example, if <1,0,0> means '1 meter in x, 0 in y and z', then you would
set Global_TheatreSys_Unit = 3. There are other global settings that can be
found by looking in the include file.
	Declaring Global_Lightsys_Brightness = 1/100 is a good starting value,
this scales the intensity of all lights in the scene. Adjust it so the
brightest light doesn't wash out to white but is otherwise as bright as
possible.

	Next, include "theatresys.inc".

	To use color gels in your lights, include any of the files beginning with
"tspd" (transmission spectral data). "tspd_colorstrings.inc" provides
standard color scroller strings.

	For an example of a proscenium theatre, you can use "PowersTheatre.inc".
This includes "PowersPositions.inc" which has basic macros for putting
borders, legs, and full stage curtains in, as well as positioning help for
where to hang lights. Look at the header of each file to see what exactly
it contains.

	To use a simple placeholder figure, include "wood_figure.inc".
	
	Demo scenes are included in the /demo folder.

===========================================================================
Reference:

	All include files have a list of public functions in the header, with
some basic description of each.

	Global Conventions:
-	In keeping with theatre CAD programs and the way most people think
of a theatre, +x is house right, +y is up, and +z is upstage. <0,0,0> is
the intersection of the center line and plaster line.

	Ellipsoidal lighting instruments:
+	SourceFour_1530Z(Location,PointAt,Intensity,Sharpness,Zoom)
	-	'Location' is a three-component vector that defines the center of the
	lighting instrument in <x,y,z> space.
	- 'PointAt' is a three-component vector that defines where the center of
	the spotlight is pointed in <x,y,z> space.
	-	'Intensity' is a value from 0 to 1, where 1 is the full brightness of
	the given lamp. Values greater than 1 will be make a brighter light, but
	does not directly relate to any real effect. Negative values have not
	been tested.
	-	'Sharpness' is a value from 0 to 1 that controls the beam spread. In
	lighting terms the field angle of the light is constant, while the
	sharpness	determines the relative size of the beam. 0 gives a fuzzy
	light with a tiny	hot spot in the middle, and 1 gives a hard edge at the
	full field width.	Values outside 0,1 may have unintended results.
	-	'Zoom' is a value from 0 to 1 that controls the field angle in a zoom
	instrument. 0 gives the narrowest angle the instrument produces, and 1 is
	the widest. 'Sharpness' determines the beam angle inside the field.

	Striplights (multi-lamp instruments):
+	PAR38_6ft_3ckt(Center,Axis,PointAt,Intensity,LampName,Color)
	-	'Center' is the middle of the instrument in <x,y,z>.
	-	'Axis' is the axis that the base of the instrument is on, for example
	<1,1,0> will position the base at a 45 degree angle in the x-y plane. It
	does not need to be a unit vector, as it is normalized inside the macro.
	-	'PointAt' is the same as in ellipsoidals, but the instrument is
	constrained to rotate around 'Axis'.
	-	'Intensity[]' is a vector of intensities for all the circuits in the
	given instrument. Each works the same as the value for ellipsoidals.
	-	'LampName' is a text string that is the name of the lamp that will
	populate the striplight. It must be the name of a macro for a lamp that is
	the correct type, or else the macro will not work. (i.e. the striplights
	that start with PAR38 must use lamps that have PAR38 in the name)
	- 'Color[]' is a vector of transmission spectra for each circuit in the
	instrument, each value should be a spline from one of the 'tspd_xxx.inc'
	files, such as 'TS_R80' for Roscolux #80 gel.
	- Intensity and Color must have at least as many values as circuits in the
	instrument, and any more will be ignored.

	PAR instruments:
+	PAR64Can(Location,PointAt,Intensity,LongAxis,LampName)
	-	'Location', 'PointAt', and 'Intensity' are the same as ellipsoidals.
	-	'LongAxis' is a vector determining the long axis of the oval of light,
	and 	can be thought of as the ground plane if the lamp is pointing
	directly down	(-y), so a value of <1,0,1> would point the oval 45 degrees
	in the x-z plane
	-	'LampName' is the same as in striplights.

	Bulbs:
-	Bulbs can be used individually, but if so the instrument accessories will
	not work.

	Instrument accessories:
	*NOTE->	All accessory macros apply to the instrument that was just created!
	- For reasons I don't fully understand, InsertGobo() must come before any
	ShutterCut_() calls, or else the shutter is ignored.
+	InsertGobo(GoboImageMap,Rotation)
	- 'GoboImageMap' is an image_map that provides a texture to shoot the light
	through. Any image can be used, you can simply download a .jpg of the gobo
	you want and put it in a map. 'filter all 1' is required for normal use.
	Example: #local Gobo = pigment{image_map{jpeg "xxxx.jpg" once filter all 1}}
	-	'Rotation' is a rotation in degrees around the lamp axis. This can be
	done using the clock variable to produce a gobo rotator in an animation.
+	InsertGel(GelSpectrum)
	- 'GelSpectrum' is a spline that defines the transmission of any wavelength
	of visible light. Full gel libraries for major manufacturers are provided
	in the 'tspd_xxx.inc' files.
+ InsertColorScroller(GelArray,Index,SnapTo)
	-	'GelArray' is an array of any number of gel colors; each value must be
	something that could be used in InsertGel.
	-	'Index' is the index of the GelArray to use. Does not need to be integer
	or within range, but if out of the range of the array the scroller will
	have unintended results.
	- 'SnapTo' is a fraction of gel frame that the scroller will lock to.
	For example, '1' means the scroller will use the nearest full color, while
	'0.5' means that the scroller can give half and half split colors.
+	InsertIris(Amount)
	-	'Amount' is how open the iris is. 0 is closed, 1 is open.
+ ShutterCut_(Amount,Angle)
	-	'Amount' is how far out the shutter is, 1 allows all light through while
	0 cuts to the center of the beam.
	- 'Angle' is degrees from normal orientation, with the middle of the
	inside edge of the shutter being the axis of rotation.

	Other Functions:
+	InsertHaze(Density,Samples,Scale)\
	- 'Density' is a somewhat arbitrary value. A predetermined 'decent' value
	is multiplied by the value, so '1' will produce a decent density haze for
	normal theatre use.
	-	'Samples' is how many samples to use in rendering, generally start at 5
	or 10 and increase until artefacts go away. Higher values make much longer
	render times.
	-	'Scale' is the scale of the 'clouds' of higher density in the haze.
	Start around 1 or 2 and modify to your liking.
	-	InsertHaze should be called within a shape that you want to have filled
	with haze. It sets the object to transparent, makes it hollow, and creates
	the media. Nothing except the basic shape should be defined in the parent
	object.

	Texture Definitions:
+ BlackPaintTexture - a decent paint texture with normals and matte finish.
+	BlackDrapeTexture - for use on black soft goods (fabric)
+	CycTexture - slightly glossy white surface for full stage cycs
+	ScrimTexture - use on extremely thin objects to simulate a scrim with
	a wide weave (letting light through the holes)

===========================================================================
Legal:

	All photometric data for instruments and bulbs were gathered from publicly
available data sheets from manufacturers or from other free online resources:
- Electronic Theatre Controls - http://www.etcconnect.com/
- Strand Lighting - http://www.strandlighting.com/
-	Williams, Bill. "The Stage Lighting Fixture Tables". Edition 2.3, 1999.
Retrieved 2009.03.13. http://www.mts.net/~william5/library/lxspot11.htm
-	BulbAmerica.com - http://bulbamerica.com/
-	StageProductionStore.com - http://www.stagelightingstore.com/

	Color filter data was obtained from data published by the manufacturers:
-	Rosco - http://www.rosco.com/
-	Lee Filters - http://www.leefilters.com/
-	Apollo - http://www.internetapollo.com/

	If something has been included that is yours, and you wish it to be
removed, please contact me and I will do my best to work something out.
