Partio43delight - c. 2012 Michal Fratczak

Partio43delight is a renderman procedural primitive, which does:
	- load particles from disk using WDAS Partio Library 
	- render them as RiPoints primitive of any type (points, blobby, ...)
	- allow to alter radius/WIDTH of cached particles
	- render 2-step motion blur derived from 'velocity' attribute
	- allow to load partitioned particle caches in one go 
		( Krakatoa naming scheme: 'particle_part1of10' ), or
	- replicate existing particles N-times with simple jitter

Partio43delight also has a 3delight4maya ( plugin, 
that lets you easily render Partio caches attached to any node,
Partio4maya visualizer recommended :).

This piece of software needs some testing and bugfixing,
use at your own risk ;)

 Procedural Primitive

	1. Copy partio43delight_procedural to your Procedural path
	2. Set RI Option: 
		Option "searchpath" "string procedural" [ "&:$DELIGHT/lib:/path/to/Partio43delight" ] 

Example RIB Calls:
	Procedural "DynamicLoad" ["partio43delight_procedural" " --type particle --radius 1.0 --radius_scale 1.0 --radius_space raster --velocity_scale 0.2 --file C:/temp/partio2/smokeShape_part.0034.bgeo"][ -5  6 -22 11 -4 5]

	Procedural "DynamicLoad" ["partio43delight_procedural" " --type particle --radius 1.0 --radius_scale 1.0 --radius_space object --velocity_scale 0.20000000298 --partitions 5 --file C:/temp/partio2/smokeShape_part$PARTof20.0034.bgeo"][ -5  6 -22 11 -4 5]

	Procedural "DynamicLoad" ["partio43delight_procedural" " --type particle --radius 1.0 --radius_scale 1.0 --radius_space world --velocity_scale 0.20000000298 --partitions 15 --merge_partitions --file C:/temp/partio2/smokeShape_part$PARTof20.0034.bgeo"][ -5  6 -22 11 -4 5]

	--type 'string'
		RiPoints primitive types. Any of: particle blobby patch sphere disk

	--radius 'float'
		RiPoints 'constantwidth'. If particle cache does not define per-particle sizes, then this flag is used

	--radius_scale 'float'
		Radius Scale.

	--radius_space 'string'
		RiPoints 'widthspace'. Any of: raster object world

	--velocity_scale 'float'
		Scales velocity attribute, and therefore motion blur. 
		Set to 0 to disable motion blur.
		If velocity is defined in units/second, then velocity_scale should be set to 1/FPS. 
		For example: particles velocity is in cm/seconds, and playback if 25FPS, 
		then velocity_scale=0.04 gives a proper length of motion blur.

	--file 'string'
		Path to cache file.

	--partitions 'int'
		If your particle caches are divided in partitions, you can render them in one step.
		File names have to follow Krakatoa naming scheme: smokeShape_part1of10.0001.bgeo
		The flag defines how many partitions to render (values go from 1 to max partitions).
		If flag is used, then --file flag has to be in form: smokeShape_part$PARTof10.0001.bgeo
		$PART key will be substituted by DSO. 
		'partitions' flag disables 'replicate' flag.

		By default, when using partitions, they are rendered as separate RiPoints() primitives.
		Setting --merge_partitions flag merges them into one prim.
		This is required if you use 'blobby' type and want the partitions to blend together.
		This flag takes no value (on/off).

	--replicate 'int'
		Replicate existing particles N-times.
		'partitions' flag disables 'replicate' flag.

	--jitter 'float'
		Jitter particles position. Indispensable when using replication.

		Modifies the jittering radius to be scaled by distance to nearest neighbour particle.
		When this flag is set, and --jitter is 1, then newly created particles will reach maximum to nearest seed particle.
		When using adaptive jitter, the jittering radius is smoothly clamped to this value.

 3delight4maya plugin

	1. Copy partio43delight directory to any location.
	2. Add this line to your userSetup.mel:
		source "/path/to/partio43delight/_INST_partio43delight.mel";

	Windows: You might need to install a zlib.dll or "Microsoft redistributable 2008" files.

	When properly installing default configuration, 
	you should be able to render partioVisualizer straight out:
		1. create partioVisualizer node
		2. add 3delight renderPass
		3. set procedural searchpath on renderPass
		4. Render !
		5. after first render, your visualizerNode will have extra attributes for cache control.

	partio43delight_maya plugin allows you to use node of any type	as a placeholder for partio caches. 
	The recommended node is partio4maya visualizer (!topic/partio-discuss/ftXklmQvtxE[1-25])
	Provided scripts are set up to handle partioVisualizer, but in case you'd like to render your own node:

	To make 3delight4maya render your node as 'partio43delight_procedural':
		1. Edit DL_userGetGeoTypeData procedure and fill 'types' array with yourNodeType
		2. Define global proc int DL_yourNodeTypeCanUseObjectInstance( string $geo ) {return 0;}		
		3. Add required attributes to the node (more on this later)

	Maya plugin defines just one command: 'partio43delight_export', 
	which in turn executes a user defined python command 'mf_partio43delight_RI'.
	The mf_partio43delight_RI accepts path to a visualizer node,
	and returns a string call to RiProcedural based on nodes attributes (cache file, time, etc.)
	Look into '' file for a partioVisualizer example.

	Older versions of partioVisualizer were derived from maya locators,
	which means maya won't lightlink them. You are advised to use latest partio4maya 
	or use 3delight4maya attribute node and sets to do lightlinking.


Build requirements:
- boost
- pystring (included)
- maya API
- 3delight API
- partio
- zlib

This code was developed on windows and linux.
You can have some problems compiling, as the CMake files are horrible and probably only work for my machines :]
They definitely need some rework to be more general.

Michal Fratczak