.\" RCSid "$Id: rtpict.1,v 1.7 2020/08/17 21:45:03 greg Exp $"
.TH RTPICT 1 3/19/2018 RADIANCE
.SH NAME
rtpict - generate a RADIANCE picture or layered image using rtrace
.SH SYNOPSIS
.B rtpict
.B "-n nproc"
[
.B "-o[vrxlLRXnNsmM] out_dir"
][
.B "-d ref_depth/unit"
]
[
.B "rpict options"
]
[
.B @file
]
.B octree
.SH DESCRIPTION
.I Rtpict
is a script that generates a picture from the RADIANCE scene given in
.I octree
and sends it to the standard output, or to a file specified with the
.I \-o
option.
Most options and defaults are the same as
.I rpict(1),
although a few switches are silently ignored.
Options incompatible with multi-processing can generate an error.
.PP
The
.I rtrace(1)
tool is called with
.I vwrays(1)
to perform the actual work.
This enables the
.I \-n
option for multiprocessing on platforms that support it.
If the
.I \-n
option is not specified or is set to 1, then
.I rpict
is called directly.
There is no benefit in setting the number of processes to anything
greater than the number of virtual cores available on your machine.
Also, it is very important to set the
.I \-af
option if an irradiance cache is being generated;
otherwise, your speed-up will be far from linear.
.PP
If the
.I \-o
option has additional characters corresponding to output types from
.I rtrace,
it must be followed by the name of a directory that either exists or
will be created to contain image layers, one per output type.
The supported types are listed below, and do not include types that
are useless or have no convenient representation.
The table below shows the correspondence between output type and file name
in the specified directory:
.sp
.nf
v	radiance.hdr
r	r_refl.hdr
x	r_unrefl.hdr
l	d_effective.dpt
L	d_firstsurf.dpt
R	d_refl.dpt
X	d_unrefl.dpt
n	perturbed.nrm
N	unperturbed.nrm
s	surface.idx
m	modifier.idx
M	material.idx
.fi
.sp
Different encodings are associated with different data types.
Color data (from the 'v', 'r', and 'x' types) will be converted to
a flat RGBE picture by
.I pvalue(1).
Distances (from the 'l', 'L', 'R', and 'X' types) will be
converted to a 16-bit representation by
.I rcode_depth(1),
and the
.I \-d
option should be used to assign the reference (median) depth and world
units, which applies to the overall scene.
Surface normals (from the 'n' and 'N' types) will be converted
to a 32-bit representation by
.I rcode_normal(1).
Finally, identifiers (from the 's', 'm', and 'M' types) will be
converted to a 16-bit index format by
.I rcode_ident(1).
.PP
If the
.I \-i
option is used to turn on irradiane output, then the picture associated
with the 'v' type will be renamed
.I "irradiance.hdr"
and some other output types become irrelevant (i.e., 'r', 'x', 'R', and 'X').
If one or more of the associated output files already exists in the
destination directory, it will be overwritten with the new data.
.SH EXAMPLES
To render a scene with four processes:
.IP "" .2i
rtpict -n 4 -vf mypers.vf -ab 1 -af scene.amb scene.oct > scene_pers.hdr
.PP
To render radiance, first surface distance, and normals in a layered image:
.IP "" .2i
rtpict -n 8 -vf fish.vf @render.opt -ovLn fisholay scene.oct
.SH NOTES
Users should seriously consider using
.I rpiece(1)
when irradiance caching is employed with a shared ambient file.
If
.I rtpict
is used in multiprocessing mode with a shared irradiance cache,
it is trying to compute almost
the same part of the same scanline in different processes, which
results in many redundant calculations.
The
.I rpiece
program avoids this by working on separate tiles in each
process, with less overlap in the indirect irradiance calculation.
Either program will benefit from an "overture" run of a
single-process rpict to create the ambient file using a low-resolution
rendering that is discarded, but this will not completely solve the
problem for
.I rtpict.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), mkpmap(1), oconv(1), pfilt(1), 
pvalue(1), rad(1), rcode_depth(1), rcode_normal(1), rcode_ident(1),
rpiece(1), rpict(1), rsplit(1), rtrace(1), rvu(1), vwrays(1),