SYNOPSIS
ptfilter -filter f [options] inputfile(s) outputfile
where f can be one of:
none
ssdiffusion
occlusion
colorbleeding
volumecolorbleeding
photonmap
sort
crop
simplify
and the options include:
-partial [0|1] (default is 0)
-organize [0|1] (default is 1)
-material [apple|chicken1|chicken2|ketchup|marble|potato|skimmilk|wholemilk|cream|skin1|skin2|spectralon]
-unitlength f (scene scale relative to mm -- for example, if scene units are centimeters use -unitlength 0.1)
-scattering f f f
-absorption f f f
-albedo f f f (or: -albedo fromfile)
-diffusemeanfreepath f f f (or: -diffusemeanfreepath fromfile)
-ior f
-smooth [0|1]
-followtopology f (between 0.0 and 1.0; default is 0.0)
-maxsolidangle f (in radians)
-rasterresolution i
-shbands i
-samplebase f
-bias f
-sides (sets both colorsides and occlusionsides)
-colorsides [front|back|both]
-occlusionsides [front|back|both]
-sides [front|back|both] (sets both colorsides and occlusionsides)
-clamp [0|1] (also allowed: -clampocclusion [0|1] or -clampbleeding [0|1])
-sortbleeding [0|1]
-areachannel s
-reflectiondirchannel s
-radiancechannel s (for ssdiffusion)
-radiositychannel s (for colorbleeding)
-envdirs [0|1]
-maxdist f
-falloff f
-falloffmode [0|1]
-bounces i
-distribution [cosine|uniform]
-coneangle f (in radians)
-mindot f (-1.0 to 1.0)
-maxdiff f
-nphotons i
-bbox f f f f f f (min xyz, max xyz)
-sources <filenames>
-positions <filenames>
-output <filename>
-progress [0|1|2]
-Progress (no argument)
-newer [0|1]
-threads i
DESCRIPTION
ptfilter reads one or more files in Pixar's point cloud file
format and generates a new point cloud file with different data. The
type of the new data is determined from the filter mode: ssdiffusion,
occlusion, colorbleeding, volumecolorbleeding, photonmap, sort, or crop.
Filter-independent Options
- -organize: set to 1 (the default), the written point cloud file is
organized; if it is set to 0, the written point cloud file is unorganized.
- -output: sets a filename for the output.
- -progress: set to 1, a few progress lines will be written out. If set to
2, more verbose information is written. The default is 0 (no progress lines
written).
- -Progress: prints R90000 progress percentages but no other progress
info. This mimics prman's -Progress behavior.
- -newer: if set to 1, only compute the point cloud if source file is newer
than destination file. The default is 0 (off).
- -threads: set the number of threads. If this option is not used, the
default is mode is single-threaded.
The ssdiffusion Filter
For the ssdiffusion filter, the input point cloud must contain
irradiance values (either direct or global illumination). The data
values of the output point cloud are computed with a subsurface
scattering diffusion approximation. The scattering properties of the
material can be specified in three equivalent ways:
- The simplest is to just specify a -material and
-unitlength. The built-in materials are apple, chicken1,
chicken2, ketchup, marble, potato, skimmilk, wholemilk, cream, skin1,
skin2, and spectralon; the data values are from [Jensen01]. The
default material is marble. The data values assume that the scene
units are mm; if this is not the case, a unitlength parameter can be
passed to ptfilter. For example, if the scene units are cm, use
-unitlength 0.1.
- Specify -scattering (the reduced scattering
coefficients, sigma's, -absorption (the absorption
coefficients, sigmaa), and -ior (index of refraction)
of the material.
- Specify -albedo (BRDF albedo), -diffusemeanfreepath, and -ior
(index of refraction) of the material. If varying albedo and/or
diffusemeanfreepath values are to be read from the input point cloud,
use -albedo fromfile and/or -diffusemeanfreepath fromfile.
The results can be noisy and aliased if the density of the source point
cloud is too sparse relative to the diffuse mean free path. Set the parameter
-smooth to 1 to overcome this problem. The default value is 0.
If subsurface scattering should be reduced across locally concave
regions such as wrinkles, skin pores, and lips, set the parameter
-followtopology to 1.0. The default value is 0.0. Values between
0.0 and 1.0 result in partial reduction across concave regions.
ssdiffusion Options
- -maxsolidangle: determines which octree nodes can be used for
calculations; it is a time/quality knob with default value of 1.0.
- -positions: if computations need to be performed at positions other than
the area point positions, a separate set of compute-positions can be
specified using -positions with a list of position point clouds.
- -partial: set to 1, an organized point cloud is written with additional
information in the octree nodes. This information can be used by the
subsurface(), occlusion(), and indirectdiffuse() functions.
- -areachannel: specifies the name of the area channel in the input point
cloud. The default name is "_area".
- -radiancechannel: specifies the name (in the input point cloud) of the
channel containing (transmitted) direct illumination. The default name is
"_radiance_t".
- -copychannels: should all data in the input point cloud be copied to
the output point cloud? Possible values are 0 or 1; default is 0.
(New for PRMan 15.1.)
The occlusion Filter
With the occlusion filter, the input point clouds must contain area
data. Each area should correspond to a micropolygon. The output is
a point cloud with ambient occlusion values, and optionally
environment directions.
occlusion Options
- -maxsolidangle: determines which octree nodes can be used for
calculations; it is a time/quality knob with default value of 1.0.
- -positions: if computations need to be performed at positions other than
the area point positions, a separate set of compute-positions can be
specified using -positions with a list of position point clouds.
- -partial: set to 1, an organized point cloud is written with additional
information in the octree nodes. This information can be used by the
subsurface(), occlusion(), and indirectdiffuse() functions.
- -areachannel: specifies the name of the area channel in the input point
cloud. The default name is "_area".
- -reflectiondirchannel: specifies the (optional) name of a channel
containing reflection directions, used to compute reflection occlusion.
- -shbands: enables the computation of spherical harmonics. The
resulting point cloud contains float channels with names
"_dirvisshcoeff0" ... "_dirvisshcoeffN", where N is shbands^2-1.
- -samplebase: determines how large an area the occlusion should
be averaged over. This is used to avoid thin stripes of missing occlusion
very close to perpendicular geometry. Values must be between 0.0 (compute
occlusion at a single point) and 1.0 (average occlusion over a micropolygon
area); the default value is 0.
- -bias: determines an offset above the surface for the occlusion
computation. Used to avoid self-occlusion (just as for ray-traced ambient
occlusion). Default value is 0.
- -sides: determines whether front, back, or both sides should
contribute occlusion. Default is both.
- -clamp: determines whether the occlusion from different surfaces should
simply be added (which often leads to too much occlusion) or clamped. The
clamped computation is more accurate, but also only half as fast. The
default is 1 (on).
- -rasterresolution: is the raster resolution for point-based
occlusion clamping. This parameter is only used if clamp is 1. Its
default value is 12, meaning that the sphere of directions is divided
into six faces with 12x12 pixels each. Using higher values gives more
accurate results, but longer render times.
- -envdirs: specifies whether environment directions should be
computed (and written in the output point cloud file). The default
is 0 (off). Environment directions are computed in world space.
The environment directions will be (0,0,0)
at those locations where the ambient occlusion is 1.
- -maxdist: the maximum distance for occlusion. The default is 1e15.
- -falloff: the occlusion falloff. Typical values are 0.0
(no falloff), 1.0 (linear falloff), and 2.0 (quadratic falloff). The
default is 0. Note that there will always be a quadratic falloff due
to distance; this parameter just specifies additional falloff.
- -falloffmode: the occlusion falloff mode. If the falloff
mode is 0, the falloff is computed as exp(-dist*falloff).
If the falloff mode is 1, the falloff is computed as
pow((1 - dist/maxdist), falloff). The default falloff mode is 0.
- -distribution: specifies whether the distribution should be
cosine or uniform. The default is cosine.
- -coneangle: specifies over how wide a cone the occlusion should be
computed. The maximum value is pi/2, which is also the default.
- -copychannels: should all data in the input point cloud be copied to
the output point cloud? Possible values are 0 or 1; default is 0.
The colorbleeding and volumecolorbleeding Filters
For the colorbleeding and volumecolorbleeding filters,
the input point clouds must contain
area and radiosity data. Each area should correspond to a
micropolygon, and the radiosity will typically have been computed by running
a shader computing direct illumination. The output is a point cloud
with color bleeding and ambient occlusion values, and optionally
environment directions. The data fields of the output point cloud are
called _occlusion, _indirectdiffuse, and _environmentdir.
Most parameters are the same as for the occlusion filter, with the following
exceptions:
colorbleeding/volumecolorbleeding Options
- -maxsolidangle: determines which octree nodes can be used for
calculations; it is a time/quality knob with default value of 1.0.
- -shbands: enables the computation of spherical harmonics. The
resulting point cloud contains float channels with names
"_dirvisshcoeff0" ... "_dirvisshcoeffN", where N is shbands^2-1.
- -positions: if computations need to be performed at positions other than
the area point positions, a separate set of compute-positions can be
specified using -positions with a list of position point clouds.
- -partial: set to 1, an organized point cloud is written with additional
information in the octree nodes. This information can be used by the
subsurface(), occlusion(), and indirectdiffuse() functions.
- -areachannel: specifies the name of the area channel in the input point
cloud. The default name is "_area".
- -radiositychannel: specifies the name of the
channel (in the input point cloud) that contains (reflected) direct
illumination. The default channel name is "_radiosity".
- -albedochannel: specifies the name of the channel that contains
albedo (diffuse color) values. The default name is "_albedo", but
the channel names "Cs", "cs", "_Cs", and "_cs" will also be accepted.
(In PRMan releases prior to 15.2, this was only used for volumecolorbleeding;
in 15.2 and higher it is used for both colorbleeding and volumecolorbleeding.)
- -extinctionchannel (volumecolorbleeding only): specifies the name of the
channel that contains volume extinction coefficients. The default name is
"_extinction".
- -sides: sets both colorsides and hitsides.
- -colorsides: determines whether front, back, or both
sides should bleed color. Default is both, but the recommended value is
front.
- -occlusionsides: determines whether front, back,
or both sides should contribute occlusion and block color bleeding.
Default is both, which is also the the recommended value.
- -sortbleeding: determines whether the color bleeding should be
sorted front-to-back and composited correctly, or simply mixed. Sorting
takes roughly 30 percent longer, but resolves color bleeding more
accurately and gives darker shadows. For the colorbleeding filter,
the default is 0 (no sorting), and sorting is only done if clamp is 1 (on).
For the volumecolorbleeding filter, sortbleeding has to be 1.
New in 15.1: sortbleeding is always on for the volumecolorbleeding filter.
- -bounces: determines how many bounces of color
bleeding should be simulated. The default is 1. For more than one
bounce, the point cloud file must contain Cs data in addition to
the area and radiosity data.
- -copychannels: should all data in the input point cloud be copied to
the output point cloud? Possible values are 0 or 1; default is 0.
The photonmap Filter
For the photonmap filter, the input point cloud must be a photon
map in which each point contains power and incident direction data.
The output is a point cloud where each point contains an irradiance
value; each irradiance value is estimated from the power and density
of the nearest n points (photons). -nphotons can be
used to specify how many points should be used for the irradiance
estimates; the default value is 50.
The sort Filter
The sort filter sorts the points in the point cloud(s) in
front-to-back order. The points are first sorted on z. Points with
the same z are sorted on y. Points with the same z and y are sorted
on x.
The crop Filter
With the crop filter only the points that
are within the given bounding box will be written out. The
bounding box is specified with the -bbox parameter.
The simplify Filter
simplify takes four parameters (two of which are optional): maxdist,
mindot, maxdiff, and rasterorient. It reads one or more point
cloud files, iteratively merges points that are closer than maxdist and have
normals that point more than mindot in the same direction. The default values
for maxdist and mindot are 1e15 and 0.5, respectively.