ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/util/trad.hlp
Revision: 2.25
Committed: Wed May 27 13:16:11 2015 UTC (8 years, 10 months ago) by greg
Branch: MAIN
Changes since 2.24: +6 -1 lines
Log Message:
Added comment about photon map sizes

File Contents

# User Rev Content
1 greg 2.19 trad.hlp 2.18 10/20/98
2 greg 2.1
3     This help file is associated with the trad interface to the Radiance
4     rad(1) program. Trad consists of trad.wsh and one do_*.tcl file for
5 greg 2.6 each screen. There are currently seven such screens: File, Scene,
6     Zone, Views, Options, Action and Results.
7 greg 2.1
8     .Trad.Intro
9    
10     Trad is a graphical user interface (GUI) to the
11     rad(1) program, which controls the operation of the basic
12     Radiance scene compiling, rendering and picture filtering programs.
13     Trad also includes links to a few utilities for displaying and
14     converting results, but most of what it does can be done by editing a
15     small text file, called the "rad input file".
16     Scene creation still requires the use of a text or graphical editor,
17     or translation from some external CAD format.
18    
19     Trad interaction is broken into seven screens.
20     Each screen is accessed by pressing its associated radio
21     button along the right-hand side of the main window.
22     If trad is started with no file name, the File screen is displayed,
23     and you must pick a valid rad input file before any other screen may
24     be accessed.
25     If a name is given for a file that doesn't exist, trad goes to the
26     Scene screen and prompts you to enter the names of one or more
27     Radiance scene description files.
28     If a rad input file exists already, trad determines if there are
29     renderings still to be done or if everything is finished.
30     If there is still work to be done, trad opens first with the Action
31     screen.
32     If all renderings are complete and up-to-date, trad opens right to
33     Results screen.
34    
35     For additional guidance on Radiance in general, consult the Radiance
36     Tutorial, Reference Manual, and man pages.
37     In particular, it is a good idea to read through the rad(1) man page
38     before using this interface.
39    
40     To find out how to get more help, press the "Next" button to the
41     right.
42    
43     .Trad.Help
44    
45     If you have specific questions about trad, search through the
46     category and topic menus on this help window, or press and release
47     the left mouse button while holding the control key over the object of
48     curiosity in the main trad window.
49     (In general, only active windows are given help file links -- click
50     on these rather than the text labels.)
51 greg 2.5 Additional search capabilities are available over all topics using
52     the "Grep" button.
53 greg 2.1
54     For help on the help facility itself, Control-click on the problem
55     help widget or on the window title in the upper right corner for
56     more general information.
57     (To get back to trad-specific help, press the "HELP" button in the
58     main trad window or Control-click on a trad widget.)
59    
60     .Trad.Messages
61    
62 greg 2.3 Informative messages, commands executed by rad, and errors
63 greg 2.1 appear in the message window at the bottom of the trad frame.
64 greg 2.3 Growing the trad window means growing this message window, and
65 greg 2.1 not much else.
66     This is not really necessary, since the window will be grown
67     automatically if the message requires it.
68    
69     Serious errors will be accompanied by the sounding of the bell.
70    
71     .Trad.Quit
72    
73     To quit the trad application, press the "Quit" button at any time.
74     If you have made changes to the rad input variables, you will be
75     asked prior to program exit if you want to save your changes first.
76    
77     Any batch process running in the background will continue to run,
78     and the associated error messages will be viewable by
79     trad later when you open the same rad input file.
80    
81     .File.Intro
82    
83     This button selects the trad File screen, which allows rad input
84     files to be loaded and saved, and new files to be created.
85    
86     .File.Load
87    
88     This button loads the selected file into trad.
89     If the current file has been changed and these changes have not been
90     saved, you will be given first the opportunity to save your changes.
91    
92     The actual load operation may take several seconds or even minutes,
93     depending on the status of the rendering process.
94     This is because the rad program itself is used to interpret the
95     input file, and if there is no up-to-date octree associated with the
96     file, it is necessary to run getbbox on the entire scene
97     before the variable values can be set.
98     It is possible to eliminate this delay in future loads by going to
99     the Action screen and running oconv.
100    
101     If the opened file has read-only mode set (see chmod(1)), then the
102     "Read Only" check box will be lit.
103     Unchecking this box means that it will be possible to save the file
104     later, though the actual mode on the file will not be changed until
105     it is saved.
106     Loading a writable file always clears the "Read Only" check box.
107    
108     If an error is encountered while trying to load the file, a message
109 greg 2.2 will be printed in the box at the bottom.
110 greg 2.1
111     .File.Save
112    
113     The "Save" button in the File screen saves any changes to the
114     current file.
115     This information is saved in the original file by default, but may
116     be saved in another file by entering a new name in the "File" field.
117     If this new file already exists, a dialogue box will ask if you really
118     want to overwrite it.
119     If the file name is different than the original
120     one loaded, the "Read Only" check box will be ignored.
121    
122     .File.New
123    
124     The "New" button clears all rad variables in preparation for
125     writing a new rad input file.
126     If the file selected already exists, a warning box will ask if you
127     really want to ignore the previous file contents.
128     If you agree, then no warning will be given when the file is later
129     overwritten.
130    
131     .File.ReadOnly
132    
133     The "Read Only" check box permits you to indicate that the opened
134     file should not be overwritten.
135     This box will be checked automatically if the permissions on the
136     edited file do not allow writing by the user.
137     If the box is subsequently unchecked, trad will attempt to change
138     permissions and write to the file when a save is requested.
139     If this fails, an error message will indicate the problem.
140    
141     .Scene.Intro
142    
143     This button selects the trad Scene screen.
144     On this screen, you may enter the octree file and the scene files
145     that go into it, as well as any mkillum or other files on which the
146     scene depends.
147     These files are generally produced by hand in a text editor or by
148     conversion from an external CAD format, such as DXF.
149     (See the Radiance Reference Manual and Radiance Tutorial for details on the
150     information contained in these files.)
151    
152     To enter a file of a particular type, press the corresponding button
153     to get a dialogue box that allows you to pick existing files from any
154     directory.
155    
156     Use the "Discard" button to remove one or more files from a specific
157     list.
158     The actual file is untouched.
159    
160     .Scene.Octree
161    
162     The "Octree" entry in the Scene screen names the octree file to be
163     compiled by oconv from the materials and scene files.
164     (See the oconv(1) man page for more details.)
165    
166     If make(1) is being used to build the octree, you should leave all
167     other windows on this screen empty.
168     The octree can still be rebuilt from trad by pressing the "oconv"
169     or "Force" buttons on the Action screen, but normally it is
170     expected to be current.
171     In particular, an unsupported octree must exist before loading
172     a rad input file on which it depends.
173    
174     The default octree name is the root name from the render input file
175     plus ".oct".
176     If mkillum is being used (i.e. one or more illum files is given),
177     then two additional octrees will be created, named the same except
178     for an additional "0" or "1" immediately before the file suffix
179     (normally ".oct").
180    
181     To delete the named octree, and therefore force the scene to be
182     recompiled and all the pictures to be rerendered, use the "Delete"
183     button next to the octree window.
184    
185     .Scene.OctDelete
186    
187     The "Delete" button next to the octree window removes the named
188     octree from the filesystem, forcing the scene to be later recompiled
189     and all the pictures to be rerendered (if desired).
190     This is appropriate if you add or remove materials, scene or illum
191     files from one or more lists, or make some change to a materials file
192     that requires the octree to be rebuilt (such as adding or removing
193     individual materials).
194    
195     Verification is required before the octree will be deleted.
196    
197     You can achieve the same effect as manually removing the octree by
198     pressing the "Force" button on the scene compilation section
199     of the Action screen.
200     (See the "Force" topic under the "Action" help category for more
201     information.)
202    
203     .Scene.Materials
204    
205     Materials files generally contain Radiance material descriptions
206     only, not geometry.
207     The purpose of listing them separately is so that minor changes to
208     material parameters will not force the octree to be rebuilt,
209     incurring an additional delay that is unnecessary.
210    
211     The "Materials" button is used to add materials files to the list.
212     A dialogue box appears when you press this button and allows you to
213     select files to be included.
214     Each new selection is added to the end of the materials list.
215     The default matching pattern for material files is "*.mat".
216     This may of course be reassigned within the file selection window.
217    
218     The list box showing the current materials may be edited in three
219     ways besides the dialogue for adding files.
220     First, entries may be removed from the list
221     using the "Discard" button.
222     Second, entries may be moved within the box by selecting them with
223     the left mouse button and clicking the middle mouse button over the
224     entry you wish to place the selected items above.
225     If you wish to put the selected items at the very end of the list,
226     click the middle mouse button below the last entry.
227     Third, entries may be moved from other windows by
228     selecting them and pressing the middle button.
229     This works for the list boxes on this screen as well as selections
230     in other windows on the display.
231    
232     The order of materials files is usually unimportant, but sometimes
233     there are definitions in later files that depend on prerequisites in
234     earlier files.
235     An example of this is a window illum source that depends on a sky
236     description file, which must appear before it.
237     The order of files shown in the list is the order they will be given
238     to oconv and therefore to the rendering programs.
239    
240     .Scene.Illum
241    
242     Illum files are Radiance scene descriptions that contain surfaces
243     to be converted into illum sources by mkillum(1).
244     Please consult the manual page for mkillum and understand the
245     Radiance Tutorial before using this box, since these files differ slightly
246     from standard Radiance scene descriptions.
247    
248     The "Illum" button is used to add illum files to the list.
249     A dialogue box appears when you press this button and allows you to
250     select files to be included.
251     Each new selection is added to the end of the illum list.
252     The default matching pattern for material files is "*.rad".
253     This may of course be reassigned within the file selection window.
254    
255     The list box showing the current illum files may be edited in three
256     ways besides the dialogue for adding files.
257     First, entries may be removed from the list
258     using the "Discard" button.
259     Second, entries may be moved within the box by selecting them with
260     the left mouse button and clicking the middle mouse button over the
261     entry you wish to place the selected items above.
262     If you wish to put the selected items at the very end of the list,
263     click the middle mouse button below the last entry.
264     Third, entries may be moved from other windows by
265     selecting them and pressing the middle button.
266     This works for the list boxes on this screen as well as selections
267     in other windows on the display.
268    
269     .Scene.Scene
270    
271     Scene files give the geometry and (perhaps) some of the materials
272     used in a particular Radiance model.
273     These files are given to oconv(1) in the order specified.
274     The ordering of files is usually not important, unless some later
275     files use materials or other modifiers defined in earlier files.
276    
277     The "Scene" button is used to add scene files to the list.
278     A dialogue box appears when you press this button and allows you to
279     select files to be included.
280     Each new selection is added to the end of the scene list.
281     The default matching pattern for material files is "*.rad".
282     This may of course be reassigned within the file selection window.
283    
284     The list box showing the current scene files may be edited in three
285     ways besides the dialogue for adding files.
286     First, entries may be removed from the list
287     using the "Discard" button.
288     Second, entries may be moved within the box by selecting them with
289     the left mouse button and clicking the middle mouse button over the
290     entry you wish to place the selected items above.
291     If you wish to put the selected items at the very end of the list,
292     click the middle mouse button below the last entry.
293     Third, entries may be moved from other windows by
294     selecting them and pressing the middle button.
295     This works for the list boxes on this screen as well as selections
296     in other windows on the display.
297    
298     .Scene.Objects
299    
300     Object files are files on which the given octree depends, but which
301     are not included directly on the oconv command line.
302     If any of these files is modified, then it is assumed that the
303     octree must be rebuilt.
304    
305     To automatically determine which files in the working directory
306     affect the octree, press the "Auto" button just below the "Objects"
307     button.
308     Note that this will only add files to the object list.
309     If you wish to completely replace what is already there, you must
310     therefore select all the files and use the "Discard" button before
311     pressing "Auto".
312    
313     .Scene.Discard
314    
315     The "Discard" button removes the selected file names from a list.
316     The actual files are untouched, of course.
317     (Some care should be taken here, since there is no undo
318     function associated with this window other than reloading the
319     original information with the "Revert" button.)
320    
321     .Scene.Edit
322    
323     Use the "Edit" button to open a text editor on the selected file(s).
324     This is a convenient way to look at and change the contents of the
325     Radiance input files.
326    
327     .Scene.Copy
328    
329     The "Copy" button may be used to selectively copy the scene file
330     information from another rad input file.
331     Specifically, the variables "OCTREE, materials, illum, scene and
332     objects" will be read in to replace the current values.
333    
334     All other variables will be unaffected.
335    
336     .Scene.Revert
337    
338 greg 2.3 The "Revert" button is a convenient way to revert to the original
339 greg 2.1 values in the rad input file.
340     Only the variables on the Scene screen will be affected, but any changes
341     to these variables since the last save will be lost.
342    
343     .Zone.Intro
344    
345     This button selects the trad Zone screen.
346     On this screen, the user should enter the maximum and minimum
347     coordinates of the zone of interest for this set of renderings.
348     This zone need not correspond exactly to any interior or exterior
349     walls, as it is used primarily to set rendering parameters and
350     standard viewpoints.
351    
352 greg 2.3 An interior zone means that standard viewpoints will be selected
353 greg 2.1 from the inside of this box.
354     An exterior zone means that standard viewpoints will be selected
355     from the outside of this box.
356 greg 2.3 The default zone is an exterior one computed from the bounding box
357 greg 2.1 of the entire scene.
358     (Note that this is not usually desirable.)
359    
360     In addition to the ZONE variable, this screen offers the ability
361     to set four other rad variables that are generally associated with a
362     particular scene and a particular zone.
363     These are the rad DETAIL, INDIRECT, VARIABILITY and EXPOSURE
364     variables.
365     For more information on these topics, use the Topic menu or consult
366     the rad manual page.
367    
368     .Zone.Type
369    
370 greg 2.3 There are two types of zones understood by rad, "Interior" and
371 greg 2.1 "Exterior".
372 greg 2.3 An interior zone is indicated when renderings generally take place
373 greg 2.1 inside a specified 3-d box.
374     A typical example might be a single room or auditorium.
375     An exterior zone is indicated when renderings generally take place
376     outside a specified 3-d box, which is the focus of attention.
377     A typical example might be a building exterior or a single object,
378     such as a chair.
379    
380     .Zone.Zone
381    
382     A zone is specified by six real numbers, corresponding to the world
383     coordinates of the box's corners.
384     Zone boxes are always axis-aligned, therefore one need only specify
385     the minimum and maximum X, Y, and Z coordinates.
386    
387     The exact values of these coordinates is not terribly important, as
388     they are only used to guide the setting of certain rendering
389     parameters and standard view positions.
390     It does not matter for instance whether the values lie on the inside
391     or the outside of walls, or if there are non-rectilinear geometries
392     defining the space perimeter.
393     In fact, the whole space may not even be aligned with the X, Y, and Z
394     axes, and a very approximate box may be given.
395     In this case, the standard views may not be very intelligent or
396     useful, but the rendering parameters will still be satisfactory so
397     long as the overall size of the given box is close to the overall
398     size of the space.
399    
400     The Zone entry windows may be manipulated in the following ways.
401     Control-V pastes the contents of the current selection at the
402     insertion point.
403     Return moves the focus to the next window in the chain.
404    
405 greg 2.17 The "Auto" button may be used to set these values based on the bounding
406     box of one or more Radiance scene files.
407    
408     .Zone.Auto
409    
410     Use this button to automatically determine the bounding box for this
411     zone, based on the output of the "getbbox" command run on one or
412     more Radiance scene files.
413     The appropriate scene files are entered via a file
414     selection dialogue box, which comes up after the button is pressed.
415    
416     The reason for selecting specific files rather than running getbbox
417     on the entire scene is that a zone usually does not include large
418     external objects, which may be present in the complete scene
419     description.
420    
421 greg 2.1 .Zone.Detail
422    
423     The "Detail" setting indicates the relative level
424     of geometric detail in this zone.
425     If the zone is empty except for a few large pieces of furniture, a
426     "Low" setting is indicated.
427     (For an exterior zone, low detail would mean that the object is
428     relatively simple.)
429     If the zone contains a usual amount of furniture and clutter, a
430     "Medium" setting is appropriate.
431     If the zone contains a great many small objects or protrusions, a
432     setting of "High" is indicated.
433    
434     This variable is used by rad to set rendering parameters that are
435     affected by the sizes of objects relative to the overall size of the
436     space.
437    
438     .Zone.Indirect
439    
440     The "Indirect" setting indicates how important indirect illumination
441     is in this space.
442     A setting of "0" means that most light falls directly on visible
443     surfaces, and this setting can be used in most cases.
444     A setting of "1" means that most objects are not directly
445     illuminated by light sources, but receive light only after it has
446     bounced once off some other surface, such as the ceiling.
447     Likewise, a setting of "2" means that light must reflect twice off
448     other surfaces before reaching most objects of interest.
449    
450     Keep in mind that the rendering calculation increases substantially
451     with each increment to this variable, so it is a good idea to use
452     the smallest reasonable value.
453    
454     .Zone.Variability
455    
456     The "Variability" setting gives a qualitative indication of how
457     light varies in magnitude over surfaces in this zone.
458     In a typical direct or indirect lighting situation, this variable
459     would be set to "Low", indicating that light is fairly uniform
460     throughout the space.
461     If there are some areas that are much better lit than others, such
462     as desks with powerful tasks lights in a room with dimmer ambient
463     lighting, a "Medium" setting is appropriate.
464     If there is direct sunlight entering the room, casting bright
465     patches on some surfaces and not others, then a setting of "High" is
466     indicated.
467    
468     Note that this variable speaks to the magnitude of light variations
469     more than the patterns of light.
470     It may well be that the light is casting interesting patterns such
471     as scallops on the walls or something, but as long as the variations
472     in brightness are less than an order of magnitude or so, it is a low
473     variability situation.
474     The high variability
475     example given above of direct sun entering a space corresponds to a
476     a variation in brightness of about three orders of magnitude, or
477     1,000 to 1!
478    
479     .Zone.Exposure
480    
481     The "Exposure" setting gives the multiplier between the initial
482     radiance values at each pixel (in watts/steradian/meter^2) to the
483     display pixel values (in the range of 0-1, where 0 is black and 1 is
484     the maximum monitor output).
485     This setting also determines the average "ambient level," which is
486     an important parameter for rendering accuracy.
487    
488     There are two basic ways to compute the exposure value.
489     The first is by trial and error, where the value is adjusted up and
490 greg 2.20 down within rvu using the "e = value" command.
491 greg 2.1 Though it sounds flaky, this is the most reliable way to set the
492     exposure (and ambient level) in general lighting situations.
493    
494     The second method is using a zonal cavity approximation.
495     For this, you must estimate the total light flux entering the zone
496     from light sources and windows, and the total illuminated area.
497     (This applies to interior zones, only. For exterior zones, use the
498     value suggested by gensky in its output.)
499     In addition, you must approximate the area-weighted average
500     reflectance of the illuminated surfaces.
501     The formula then for the exposure multiplier using this information
502     is: pi*tot_area*(1-avg_refl)/(2*tot_flux*avg_refl)
503     where pi is 3.1416, tot_area is given in square meters and
504     tot_flux is given in watts.
505     (Divide total lumens by 179 lumens/watt to get watts.)
506    
507     The exposure value may either be given as a positive real value, or
508 greg 2.16 as a real value preceded by a '+' or '-' indicating a positive or
509 greg 2.1 negative number of f-stops (powers of two) from the original value.
510    
511     If no exposure is given, pfilt will automatically compute the
512     average for each image, and a default ambient level of 10 will be
513     used for exterior zones and 0.01 for interior zones.
514    
515     .Zone.Copy
516    
517     The "Copy" button on the Zone screen takes all values for this
518     screen from another rad input file, replacing the current values.
519 greg 2.3 Specifically, the rad variables "ZONE, DETAIL, INDIRECT,
520 greg 2.1 VARIABILITY and EXPOSURE" will be copied from the named file.
521    
522     All other variables will be left untouched.
523    
524     .Zone.Revert
525    
526 greg 2.3 The "Revert" button is a convenient way to revert to the original
527 greg 2.1 values in the rad input file.
528     Only the variables on the Zone screen will be affected, but any changes
529     to these variables since the last save will be lost.
530    
531     .Views.Intro
532    
533     This button selects the trad Views screen.
534     This screen provides a means of setting the multi-valued
535     "view" variable.
536     Each view setting is listed by name, or by number if no name has
537     been assigned.
538 greg 2.3 To add a new view, enter a unique name and specify the view
539 greg 2.1 options,
540     then press the "Add" or "Set Default" button.
541     If a view with the same name already exists, it is unconditionally
542     overwritten.
543     To modify a particular view, simply select it, change its name
544     and/or parameters, and press the "Change" button.
545     To remove an unwanted view, select it and press the "Delete" button.
546     To undo this action, simply press the "Add" button again.
547    
548 greg 2.20 The first view in the list is the default given to rvu during
549 greg 2.1 interactive rendering, and is the first view rendered in a batch run.
550     To change the default view, select the newly desired view and press
551     the "Set Default" button.
552     This button also acts like the "Add" button inasmuch as a new view
553     may be entered and this button will add it and make it the default
554     at the same time.
555    
556     The Views screen also allows the standard view up vector to be
557     changed, as well as the root picture name and the output resolution.
558    
559     .Views.List
560    
561     The list box on the far left of the Views screen shows the
562     currently defined view names.
563     Clicking on any of these with the left mouse button shows the view
564     parameters and allows the view to be edited.
565    
566     To change the name or options, edit the "Name" or "Options"
567     entry and click on the "Change" button.
568    
569     Use the "Add" button to add a new view, which may be modified from
570     an old one by changing the name and options.
571    
572     Use the "Delete" button to delete the selected view from the list.
573    
574     Views are listed in the order in which they appear in
575     the rad input file.
576    
577     The standard view is "X" is used if no views are specified.
578    
579     .Views.Name
580    
581     Each view has a unique name, which may be chosen at the user's
582     discretion or taken from a list of standard views, described below.
583 greg 2.3 An invented name should be kept as short as possible, since it is
584 greg 2.1 added to the picture file name along with the standard ".pic" suffix.
585    
586     The standard views are specified by strings of the form
587 greg 2.23 "[Xx]?[Yy]?[Zz]?[vlahsc]?".
588 greg 2.1 (That is, an optional upper or lower case X followed by an optional
589     upper or lower case Y followed by an optional upper or lower case Z
590 greg 2.23 followed by an optional lower case view type.)
591 greg 2.1 The letters indicate the desired view position, where upper case "X"
592     means maximum X, lower case "y" means minimum Y and so on.
593     The final letter is the view type, where 'v' is perspective (the
594 greg 2.12 default), 'l' is parallel, 'a' is angular fisheye, 'h' is
595 greg 2.23 hemispherical fisheye, 's' is for planisphere (stereographic) fisheye,
596     and 'c' is for cylindrical panorama.
597     A perspective view from maximum X, minimum Y would be "Xy" or "Xyv".
598 greg 2.1 A parallel view from maximum Z would be "Zl".
599     If "ZONE" is an interior zone, the standard views will
600     be inside the perimeter.
601     If it is an exterior zone, the standard views will be outside.
602     Note that the standard views are best used as starting points,
603     and additional arguments may be given after the
604     identifier to modify a standard view to suit a particular model.
605    
606     .Views.Options
607    
608     The "Options" entry window is where the Radiance view
609     corresponding to the selected name is given.
610     If the view is one of the standard names (described in the "Views
611     Name" section), then the options are truly optional, and will
612     modify the standard view.
613     Otherwise, it is usually necessary to specify a set of options to
614     define a view.
615    
616     The simplest view specification is of the form "-vf viewfile", where
617 greg 2.20 "viewfile" is a file created with the rvu "view" command, or a
618 greg 2.1 Radiance picture.
619     This method of naming views, although convenient, is not the best
620     since it is difficult to know exactly where such a view is by
621     seeing only its file name.
622     Also, the file may change or be moved or removed, and then the view
623     may be different than expected or gone altogether.
624    
625     To add view options selected from another X11 window, select the
626     text from another window in the normal fashion, use the left mouse
627     button to click on the insertion point in the options string, then
628     use Control-V to insert the text at that point.
629     For convenience, the middle mouse button has been made
630     equivalent to Control-V in this window, but it is not the normal
631     interaction mode for trad.
632    
633     Consult the rpict(1) manual page for a full description of the various
634     view options, all of which begin with "-v".
635     Just briefly, the "-vt?" option sets the view type, where "?" is
636 greg 2.23 replaced by one of the letters "v, l, a, h, s or c", corresponding to
637 greg 2.12 perspective, parallel, angular fisheye, hemispherical fisheye
638     and cylindrical panorama, respectively.
639 greg 2.3 The "-vp x y z" option sets the view position (eyepoint), where "x y z"
640 greg 2.1 is replaced by the position in 3-space.
641     The "-vd xd yd zd" option sets the view direction, where "xd yd zd"
642     is a vector pointing in the desired direction.
643     (To compute this direction from a "look-at" point, simply subtract
644     the eyepoint from the look-at point. Vector normalization is
645     unnecessary.)
646     The "-vh horiz" and "-vv vert" options set the horizontal and
647     vertical view sizes, respectively.
648 greg 2.3 For perspective views, these correspond to full camera angles in
649 greg 2.1 degrees.
650     For parallel views (using the "-vtl" option), they correspond to
651     image plane size in world coordinates.
652     The lesser used "-vu xd yd zd", "-vs vs" and "-vl vl" options
653     will not be discussed here.
654    
655     The order of the view options is irrelevant, unless the same option
656     is given twice, in which case the last one is used.
657     Trad does not check the syntax of the view options strings, so be
658     careful!
659     In particular, make sure that each option and each argument has a
660     space between it and whatever follows.
661    
662     Hitting return in the "Options" window is equivalent to pressing the
663 greg 2.4 "Add" button followed by the "Clear" button.
664 greg 2.1
665     .Views.Add
666    
667     The view "Add" button takes the currently defined view given by the
668     "Name" and "Options" windows and appends it to the list of views.
669     If another view by the same name exists, it is removed first.
670    
671     Since the view is added to the end of the "Views" list, the "Add"
672     button is a convenient way to move views to a lower-priority
673     position.
674     Simply select the view you wish to be last and press "Add".
675    
676     To add a view as the first (i.e. the default) view instead of the
677     last, use the "Set Default" button.
678    
679     .Views.Change
680    
681     The view "Change" button deletes the currently selected view and
682     adds the currently defined view in its place, changing the name
683     and/or view options in the process.
684    
685     .Views.Delete
686    
687     The view "Delete" button removes the currently selected view from
688     the view list.
689    
690     To undo this action, simply press the "Add" button immediately
691     afterwards, while the deleted view is still present in the edit
692     window.
693    
694     .Views.Clear
695    
696     The "Clear" button simply clears the "Name" and "Options" windows
697     for the convenience of entering a new view.
698     It has no effect on the rad input variables.
699    
700     .Views.Default
701    
702     The "Set Default" button may be used to make the selected view the
703     default view for rendering.
704     This simply moves the view to the top of the list in the rad input file.
705 greg 2.20 The default view will be the one normally rendered by rvu when rad
706 greg 2.1 is started interactively, and is the first view rendered in a batch
707     process.
708    
709     A new view may be added as the default view by pressing the "Set
710     Default" button rather than the "Add" button.
711     It is never necessary to press both.
712    
713     If the selected view is already the default, this button will be
714     disabled and will read "Is Default" instead of "Set Default".
715    
716     .Views.Up
717    
718     The standard view up vector may be set to the positive X axis (+X),
719     the positive Y axis (+Y), the positive Z axis (+Z), the negative
720     X axis (-X), the negative Y axis (-Y), or the negative Z axis (-Z).
721    
722 greg 2.16 This setting may always be overridden by the "-vu xd yd zd" option,
723 greg 2.1 and will be altered for a particular view if it happens to be
724     parallel to the view direction.
725    
726 gwlarson 2.18 .Views.Eyesep
727    
728     The eye separation is used for generating stereo views of
729     the scene.
730     It is the measured distance between a viewer's pupils in world
731     coordinate units.
732     It is not used directly by rad, but should be set for other programs
733     that need it, such as rholo and glrad.
734    
735 greg 2.1 .Views.Picture
736    
737     The root picture file name is given in the "Picture" entry window.
738     To this will be added an underscore, followed by the name of
739     the particular view being rendered, followed by the ".pic" suffix.
740    
741     To render pictures into a different directory than the one
742     containing the rad input file, simply precede the file name by a
743     relative or absolute directory.
744     (Do not use the tilde shorthand for home directories,
745     as it is not guaranteed to work on all systems.)
746    
747     The default picture name is the root name of the rad input file.
748    
749     .Views.Resolution
750    
751     The final picture resolution is set in the "Resolution" entry
752     window.
753     The first entry is the X resolution (in pixels), and the second
754     (optional) entry is the Y resolution.
755     If there is only one entry, the maximum X and Y resolution will be
756     equal.
757     If a third entry is given, it is taken as the aspect ratio of the
758     destination pixels.
759     A number greater than one means that the pixels on the destination
760     device are taller than they are wide (and therefore there are more
761     of them horizontally than vertically spanning a like distance), and
762     a number less than one means the opposite.
763     An aspect ratio of zero means that the exact given X and Y
764     dimensions are to be honored, whatever the resulting pixel ratio.
765     Normally, either the X or the Y resolution is reduced as necessary
766     to maintain a specific pixel aspect ratio (1 by default).
767    
768     The default value for this variable is "512".
769    
770 greg 2.13 .Views.Rawfile
771 greg 2.11
772 greg 2.13 The "Rawfile" entry window determines if and where the raw output picture
773 greg 2.11 from rpict will be saved.
774 greg 2.13 If the entry is empty, the file will be removed after rendering and
775     filtering.
776     This is the normal action, since the raw file
777 greg 2.11 takes up disk space and is not generally useful.
778 greg 2.13 However, if you wish to perform some special filtering function,
779     this file can be renamed instead of removed by giving a
780     root file name in this entry window.
781     The final name in this case will be the given root plus and
782     underscore plus the view name followed by a ".pic" suffix.
783    
784     In the special case when the raw file name and picture file name are
785     the same, the raw file is saved and no filtering takes place.
786    
787     .Views.Zfile
788    
789     The "Zfile" entry window gives the root name of the file in which to
790     store the raw (binary floating point) distances to pixels in the
791     original generated image.
792     If this entry is empty, then no z-file will be saved.
793    
794     The final z-file name will be the given root plus an underscore plus
795     the view name plus a ".zbf" suffix.
796    
797     To convert this image to human-readable form, the program "od" will
798     work on some systems, or the Radiance "pvalue" program may be used
799     to first convert it to a greyscale Radiance picture using the
800     options "-r -h -b -df `getinfo -d < pictname`" where "pictname" is
801     replaced by the raw picture file name.
802     (Getinfo simply gets the original image dimensions, which are not
803     stored in the z-file.)
804 greg 2.11
805 greg 2.1 .Views.Copy
806    
807     The "Copy" button in the Views screen permits those variables
808     represented on this screen to be copied from another rad input file.
809     Specifically, the affected variables are "view, UP, PICTURE, and
810     RESOLUTION".
811    
812     The original values will be lost, and all other variables will be
813     untouched.
814    
815     .Views.Revert
816    
817 greg 2.3 The "Revert" button is a convenient way to revert to the original
818 greg 2.1 values in the rad input file.
819     Only the variables on the Views screen will be affected, but any changes
820     to these variables since the last save will be lost.
821    
822     .Options.Intro
823    
824     This button selects the trad Options screen.
825     This screen allows the setting of various options for
826     controlling the rendering process.
827     The most general option is rendering "Quality", which determines the
828     overall accuracy and beauty of the pictures produced.
829     A separate "Penumbras" option indicates the importance of soft
830     shadows in this scene.
831     The "Ambfile" variable allows you to specify a file for sharing
832     ambient files between runs, and it is recommended that you set
833     this variable for high quality renderings.
834     The "Optfile" variable allows you to specify a separate file for
835     storing rendering options, which reduces the size of the command
836     line and makes it easier to run programs such as rtrace(1).
837     The "Report" variable may be used to specify a time interval (in
838     minutes) between progress reports.
839    
840     Other windows allow the user to customize the options to oconv(1),
841 greg 2.20 mkillum(1), rvu(1) and rpict(1), and pfilt(1).
842 greg 2.1
843     .Options.Quality
844    
845     The "Quality" setting affects the overall accuracy and beauty of the
846     renderings produced.
847    
848     A "Low" setting is appropriate for quick checks of scene geometry and
849     crude lighting studies.
850     No interreflection calculation will take place, regardless of the
851     setting of the "INDIRECT" variable, and other options are tuned for
852     speed over accuracy.
853     The computed picture size will exactly equal the final picture
854     size, thus some aliasing may be apparent.
855    
856     A "Medium" quality setting is most often used for draft renderings, as
857     it provides a good balance between rendering time and accuracy.
858     The number of interreflections calculated will be equal to the
859     setting of the "INDIRECT" variable.
860     The computed picture size will be twice the final size, for a modest
861     degree of anti-aliasing.
862    
863     A "High" quality setting is usually reserved for final renderings.
864     The number of interreflections computed will equal the value of the
865     "INDIRECT" variable plus one, to guarantee accuracy.
866     The computed picture size will be three times the final size, so
867     aliasing artifacts should be negligible.
868    
869     When increasing the value of the "Quality" setting, it is usually a
870     good idea to delete the old "Ambfile", if there is one.
871     (See the "AmbDelete" topic under the current help category for
872     details.)
873    
874     .Options.Penumbras
875    
876 greg 2.3 The "Penumbras" setting determines whether or not Radiance will
877 greg 2.1 make a special effort to generate soft shadows from area light sources.
878     Since this is a potentially expensive calculation, penumbras should
879     only be switched "On" when they are really needed.
880    
881     Leaving this setting "Off" does not mean that area light sources
882     will be treated as points.
883     It only means that some accuracy and possibly some smoothness
884     will be traded for speed in the shadow calculations.
885    
886 greg 2.24 .Options.Pgmap
887    
888     The "Pgmap" specifies the file to hold the global photons computed
889     by the "mkpmap" command, followed by the number of photons to generate
890     (required).
891     A typical photon count for a global map is on the order of 100-200K.
892 greg 2.25 (A 'K', 'M', or 'G' may follow the value to indicate 1000's, millions,
893     or billions of photons.)
894 greg 2.24 By convention, photon map files are given a ".pmp" suffix.
895     An optional third parameter specifies the bandwidth to use
896     for the global photons during rendering, and this value should be
897     around 50.
898    
899     .Options.PgmDelete
900    
901     The "Delete" button next to the "Pgmap" window on the Options
902     screen allows you to remove the named global photon map file.
903     This is usually done when a change is made to the "mkpmap" options,
904     as the file will be regenerated automatically after most scene changes.
905    
906     .Options.Pcmap
907    
908     The "Pcmap" specifies the file to hold the caustic photons computed
909     by the "mkpmap" command, followed by the number of photons to generate
910     (required).
911 greg 2.25 A typical photon count for a global map is on the order of 1000K (1M).
912     (A 'K', 'M', or 'G' may follow the value to indicate 1000's, millions,
913     or billions of photons.)
914 greg 2.24 By convention, photon map files are given a ".pmp" suffix.
915     An optional third parameter specifies the bandwidth to use
916     for the global photons during rendering, and this value should be
917     around 50.
918 greg 2.25 (See the "Pgmap" topic under the current help category.)
919 greg 2.24
920     .Options.PcmDelete
921    
922     The "Delete" button next to the "Pcmap" window on the Options
923     screen allows you to remove the named caustic photon map file.
924     This is usually done when a change is made to the "mkpmap" options,
925     as the file will be regenerated automatically after most scene changes.
926    
927 greg 2.1 .Options.Ambfile
928    
929     The "Ambfile" is the file used to store Radiance ambient values for
930     later reuse in other renderings.
931     This can greatly reduce the time required to generate multiple
932     views, as well as improve the quality of a single view whenever
933     interreflections are computed.
934    
935     It is strongly recommended that the user set this variable, especially
936     when the "QUALITY" variable is set to "High".
937     The usual convention is to use the root name of the rad input file,
938     followed with the ".amb" suffix.
939     It is generally not a good idea to share ambient files between
940     different zones, as the placement and accuracy of these values will
941     vary according to the location and characteristics of each zone.
942    
943     .Options.AmbDelete
944    
945 greg 2.3 The "Delete" button next to the "Ambfile" window on the Options
946 greg 2.1 screens allows you to remove the named ambient file.
947     This is usually done when a change to one or more rad variables
948     casts doubt on the accuracy of the values stored in this file.
949     In particular, increases in the variables, "DETAIL, INDIRECT,
950     VARIABILITY, EXPOSURE or QUALITY" generally invalidate this file.
951    
952     If the ambient file is not empty, you will be asked to verify this
953     operation since the values may represent a significant computational
954     effort.
955    
956     .Options.Optfile
957    
958     The "Optfile" setting assigns a file to hold rendering options,
959     which may be a convenience when these options are reused for
960 greg 2.20 rtrace(1) or rpiece(1), or manual invocations of rvu or rpict.
961 greg 2.1 Using an options file also reduces the size of the command line,
962     making it a little easier on the eye.
963    
964     To assure that the "Optfile" contents are up-to-date, you should press
965     the "oconv" or "Script" button on the Action screen.
966    
967     .Options.Report
968    
969     The "Report" setting indicates the time interval (in minutes)
970     between rpict progress reports.
971     Normally, rpict runs silently, but it is often nice to know how far
972     a given rendering has progressed.
973     Normally, progress reports and errors during batch renderings
974     are sent to the error file given by the root of the rad input
975     file name followed by the ".err" suffix.
976 greg 2.9 (See the "CheckErr" topic under the "Action" screen category.)
977 greg 2.1 If you wish these reports and errors to be directed to a different
978     file, follow the time interval by a space and a file name.
979    
980     No setting on this variable means do not report rendering progress.
981 greg 2.3 A zero setting means the same thing, and may be used when a
982 greg 2.1 separate error file is desired but progress reports are not.
983    
984     .Options.Oconv
985    
986     The "oconv opts" window may be used to specify any additional
987     options to the oconv(1) command used to compile the scene
988     description.
989    
990     In particular, the "-f" option for creating a "frozen" octree may
991     speed rendering start-up substantially, although it makes it
992     impossible to change even material properties without
993     recompiling the scene again.
994     (The "-f" option is technically incompatible with naming
995     "materials" files on the Scene screen.)
996    
997     If oconv generates a "set overflow" error, it may mean that the "-r
998     res" option is needed to increase the octree resolution.
999     See the oconv(1) man page for details.
1000    
1001     The "-i octree" option should be used with extreme caution, as incremental
1002     building of octrees is not very well supported by rad.
1003     You may do it this way if you specify the input octree as one of the
1004     "Objects" files on the Scene screen, but it is preferable to use the
1005     UNIX make(1) utility to incrementally build the octree instead, and
1006     indicate this by not specifying any illum or scene files.
1007    
1008     .Options.Mkillum
1009    
1010     The "mkillum opts" window may be used to specify options to the
1011 greg 2.24 mkillum(1) command.
1012 greg 2.1 These options apply only if there are one or more "Illum" files
1013     named on the Scene screen.
1014    
1015     It is very important to set mkillum options sensibly,
1016     since rad does not have the intelligence to do it for you.
1017    
1018 greg 2.24 .Options.Mkpmap
1019    
1020     The "mkpmap opts" window may be used to specify options
1021     to the mkpmap(1) command.
1022     There are no default values, and rad does not set these
1023     options intelligently.
1024    
1025 greg 2.1 .Options.Render
1026    
1027     The "render opts" window is used to specify additional options to
1028 greg 2.20 the rvu(1) and rpict(1) rendering programs.
1029 greg 2.3 Most of the important parameters are computed by rad, so this
1030 greg 2.1 window is usually used to override specific parameters or to give
1031     additional information, such as which materials to exclude from the
1032     interreflection calculation.
1033    
1034     .Options.Pfilt
1035    
1036     The "pfilt opts" window is used to specify additional options to
1037     the pfilt(1) picture filtering program.
1038    
1039     Note that the "-e expval", "-x xres" and "-y yres" options are
1040     already dictated by the settings of the "EXPOSURE" and "RESOLUTION"
1041     variables, and should therefore be used with caution.
1042    
1043     Also note that the setting of some pfilt options require a
1044     two-pass filtering process, rather than the default single pass.
1045     If no "EXPOSURE" setting is given, this is not a problem, but if a
1046     value for the "EXPOSURE" variable is set as recommended, then it is
1047     necessary to manually specify the "-2" option to pfilt, followed by
1048     an exposure that undoes the "EXPOSURE" setting.
1049     An equivalent workaround is to unset the EXPOSURE variable and
1050     manually set the render option "-av V V V", where "V" is equal to
1051     0.5/old_EXPOSURE.
1052    
1053     .Options.Copy
1054    
1055     The "Copy" button in the Options screen permits those variables
1056     represented on this screen to be copied from another rad input file.
1057     Specifically, the affected variables are "QUALITY, PENUMBRAS,
1058     AMBFILE, OPTFILE, REPORT, oconv, mkillum, render and pfilt".
1059    
1060     The original values will be lost, and all other variables will be
1061     untouched.
1062    
1063     .Options.Revert
1064    
1065     The "Revert" button is a convenient way to revert to the original values
1066     in the rad input file.
1067     Only the variables on the Options screen will be affected, but any changes
1068     to these variables since the last save will be lost.
1069    
1070     .Action.Intro
1071    
1072     This button selects the trad Action screen.
1073     This screen is where the actual Radiance programs are
1074     run, usually via rad(1).
1075     The top row of buttons is used to update the octree following a
1076     change to one or more input files.
1077 greg 2.20 The "rvu" button starts an interactive rendering in the
1078 greg 2.1 foreground.
1079     The next set of buttons provides for the control of a batch
1080     rendering process, taking place in the background.
1081     Finally, the bottom set of buttons allows you to preview what would
1082 greg 2.3 happen during a batch rendering, or (equivalently) make a script of
1083 greg 2.1 UNIX commands for later execution.
1084    
1085     When the Action screen is first brought up, the message window
1086     displays the current status of any batch rendering process.
1087     The status must either be "No batch rendering in progress," which
1088     means that as far as trad can tell a batch rendering was never
1089     started, "Batch rendering stopped," meaning that there is no current
1090     process but at least some views have not been rendered or are
1091     out-of-date, or "Batch rendering finished," meaning that everything
1092     is done.
1093    
1094     .Action.Oconv
1095    
1096     The "oconv" button on the Action screen may be used to manually
1097     compile the scene description and bring the octree up to date.
1098     It is normally not necessary to use this button, since the octree
1099     will be rebuilt if appropriate prior to rendering.
1100     However, if the octree is maintained by make(1) rather than rad, or
1101     the octree was never created and you want trad to start a little
1102     faster next time, or you just need the octree for some reason other
1103     than rendering, this is the button for you.
1104    
1105     If you have made changes to the rad variables or the Radiance
1106     material files that invalidate the current octree or renderings but
1107     would not automatically rebuild the octree because the scene files
1108     themselves were not changed, it may be wise to use the "Force"
1109     button.
1110     In contrast, if you have made some insignificant changes to the
1111     scene files that should not make any difference to the octree or the
1112     renderings, you may want to use the "Touch" button.
1113    
1114     Pressing the "oconv" button also updates the contents of the
1115     "Optfile" if one is given on the Options screen.
1116     This may be useful for computing rendering parameters for rtrace(1)
1117     or rpiece(1).
1118    
1119     .Action.Force
1120    
1121     The "Force" button on the Action screen
1122     causes the octree to be unconditionally rebuilt,
1123     by removing it first.
1124     This will also require all pictures to be rerendered, so only use
1125     this button if it is really necessary, i.e. if you have made
1126     some important changes to the rad
1127     variables on the Scene, Zone or Options screens, but have not
1128     changed any scene file on which the octree depends.
1129    
1130     If the octree itself should not be affected by these changes, only
1131     the renderings, you may delete the faulty picture files instead from
1132     the Results screen and the ambient file (if it exists) from the
1133     Options screen.
1134    
1135     .Action.Touch
1136    
1137     The "Touch" button on the Action screen
1138     should be used when some insignificant change has
1139     been made to the Radiance input files, which might otherwise cause
1140     the octree to be rebuilt and the picture files to be rerendered.
1141    
1142     Care should be exercised in using this button since you may have
1143     made a change that really does affect the octree in an important
1144     way.
1145     Even something as seemingly trivial as deleting an unused material
1146     will cause an unfrozen octree to become invalid and unusable.
1147    
1148     Therefore, if you know the octree should be rebuilt, but you do not
1149     want to cause any of the currently rendered pictures to be redone,
1150     press the "oconv" button to bring the octree up to date, followed
1151     by the "Touch" button.
1152     (This will still cause the ambient file to be removed,
1153     unfortunately.)
1154    
1155 greg 2.20 .Action.Rvu
1156 greg 2.1
1157 greg 2.20 The "rvu" button on the Action screen starts an interactive
1158 greg 2.3 rendering for the selected view, indicated by the menu button
1159 greg 2.1 just to the right.
1160 greg 2.20 Other views may be accessed within rvu using the "L name"
1161 greg 2.3 command, and new views can be added with the "V name"
1162 greg 2.1 command.
1163 greg 2.6
1164     When using the "V" command to change an existing view, do not
1165 greg 2.10 give it an existing name because the previous view will not be overridden.
1166 greg 2.6 Instead, give it a new name (or no name, which will show up as
1167     a number later), then use the Views screen to override the previous
1168     view definition with the new one.
1169 greg 2.10 (See the "View" topic in the current
1170 greg 2.20 help category, the "Change" topic under "Views" and the rvu(1)
1171 greg 2.10 manual page for more information.)
1172 greg 2.1
1173 greg 2.3 If the octree is out-of-date, it will be rebuilt before rendering
1174 greg 2.1 begins.
1175    
1176     .Action.View
1177    
1178     The Action screen contains two menus for selecting views.
1179 greg 2.20 The top menu, next to the "rvu" button, sets the view to start
1180     with in rvu, and is selected from the current view list.
1181 greg 2.3 The second view menu, next to the "Start" button for batch
1182 greg 2.1 rendering, selects the view or views to render in batch mode.
1183 greg 2.3 If the special entry "ALL" is selected, then every view in the
1184 greg 2.1 current list will be rendered if it hasn't been already.
1185    
1186 greg 2.20 The view menu next to the "rvu" button will be disabled if there
1187 greg 2.7 is only one view to choose from.
1188     The view menu next to the "Start" button will be disabled if there
1189     is a batch job in progress, and thus the view cannot be changed.
1190    
1191 greg 2.3 The batch rendering view menu also selects the view or views
1192 greg 2.1 to use in producing a script during a dry run.
1193    
1194 greg 2.21 .Action.Processes
1195    
1196     The "Number of processes" slider controls how many independent
1197     processes are initiated by the "rvu" and "Start" buttons above
1198     and below.
1199     This should be set no greater than the number of virtual cores
1200     on your system.
1201    
1202     For interactive rendering, the "new" command within rvu may
1203     be used to change the number of processes running.
1204    
1205     For rendering in the background, the number of processes will
1206     never be greater than the number of views if all views are
1207 greg 2.22 being rendered.
1208     If only a single view is selected for rendering, rad
1209     will call rpiece to render it in tiles using the given
1210 greg 2.21 number of processes.
1211    
1212 greg 2.1 .Action.Start
1213    
1214 greg 2.3 The "Start" button for batch rendering on the Action screen
1215     initiates a rad rendering process in the background using the
1216 greg 2.1 selected view or views shown on the menu button to the right.
1217    
1218     If any of the rad variables have been changed since the
1219     file was last saved, you will first be asked if you wish to save
1220     your changes before starting a background process.
1221     If you discard these changes, then the batch rendering will be
1222     conducted using the previously saved values.
1223    
1224 greg 2.3 Once a background process is going, the "Start" button is
1225     disabled, and rendering progress can be monitored by checking
1226 greg 2.1 the error file periodically.
1227 greg 2.3 (This file is named by the root of the rad input file followed by
1228 greg 2.1 ".err".)
1229 greg 2.8 When a batch process is started or already running, or when a
1230     process is on another host and its status is unknown,
1231     this button will be disabled.
1232 greg 2.1
1233 greg 2.3 The background process can be killed during this or later
1234 greg 2.1 invocations of trad using the "Kill" button.
1235 greg 2.8 If the process was started on another machine and the status is unknown,
1236     it will be necessary to run trad from the other host or remove the error
1237     file manually before starting a background process on this machine.
1238     This is to protect you from the great confusion that results when two
1239     machines are working from the same project file.
1240 greg 2.1
1241     .Action.Kill
1242    
1243 greg 2.3 The batch rendering "Kill" button kills the
1244 greg 2.1 background process started earlier with the "Start" button.
1245 greg 2.3 The rad process id is taken from the first line of the error file,
1246 greg 2.1 and this process and all its children are killed when the
1247     button is pressed.
1248    
1249 greg 2.3 So long as there is an ambient file specified in the Options
1250     screen, no data is lost by killing and restarting a batch
1251 greg 2.1 rendering, though some new startup costs will be incurred.
1252    
1253 greg 2.3 The "Kill" button is disabled if no running batch process is
1254 greg 2.8 detected on the current host machine.
1255 greg 2.1
1256     .Action.CheckErr
1257    
1258     Pressing the "Check errors" button
1259 greg 2.3 displays the contents of the batch rendering error file, named
1260     by the root of the current rad input file followed by the ".err"
1261 greg 2.1 suffix.
1262 greg 2.3 This file will contain the command lines executed by rad so far,
1263     and may or may not contain additional progress reports from
1264 greg 2.1 rpict, depending on the initial setting of the "REPORT" variable.
1265    
1266     If no error file exists, this button will be disabled.
1267    
1268     .Action.Script
1269    
1270     The dry run "Script" button runs rad with the
1271 greg 2.3 "-n" option so that you may see the commands that would be
1272 greg 2.1 executed during a batch run without actually executing them.
1273 greg 2.3 If a file is named in the window next to this button, the output
1274 greg 2.1 will simply be written to that file.
1275 greg 2.3 If no file is named, a temporary file is created and an editor
1276 greg 2.1 window is opened on it.
1277    
1278     Producing a dry run also writes the "Optfile" if one is specified
1279     on the Options screen.
1280     This may be useful for computing rendering parameters for rtrace(1)
1281     or rpiece(1).
1282    
1283 greg 2.3 The view or views are selected by the same menu used for
1284 greg 2.1 batch rendering.
1285 greg 2.3 (See the "View" topic under the current help category for more
1286 greg 2.1 information.)
1287    
1288     .Action.Edit
1289    
1290 greg 2.3 The dry run "Edit" button is used to edit the named script file
1291 greg 2.1 created by pressing the "Script" button.
1292     If no file is named, this button is ineffective.
1293    
1294     .Action.Delete
1295    
1296 greg 2.3 The "Delete" button removes the named script file, created by the
1297 greg 2.1 "Script" button.
1298 greg 2.3 If no file is named, or the named file does not exist, this button has
1299 greg 2.1 no effect.
1300    
1301     .Results.Intro
1302    
1303     This button selects the trad Results screen.
1304 greg 2.3 This screen permits rendered pictures to be displayed,
1305 greg 2.1 converted to other image formats, and printed.
1306 greg 2.3 Only finished pictures may be converted or printed, but
1307     incomplete pictures (i.e. aborted renderings or renderings in
1308 greg 2.1 progress) may be displayed interactively.
1309    
1310     The left-hand window shows a list of completed views, and the
1311 greg 2.3 right-hand window shows views that have been started but not
1312 greg 2.1 finished.
1313 greg 2.3 Note that other views may not even be started, thus may not
1314 greg 2.1 appear in either list.
1315 greg 2.3 Also, just because a view appears on the Results screen, it does
1316     not mean that view is up-to-date with respect to the Radiance
1317 greg 2.1 input files.
1318 greg 2.3 (The best way currently to tell which pictures are out-of-date
1319     is to press the "Script" button on the Action screen and examine
1320 greg 2.1 the output.)
1321    
1322     .Results.Finished
1323    
1324     The "Finished views" list box on the Results screen shows those
1325     renderings which have completed, whether or not they are up-to-date
1326     with respect to the Radiance input files.
1327     Select pictures in this box for display, conversion to other image
1328     formats, and/or printing.
1329     Selected pictures may also be deleted with the "Delete" button.
1330    
1331     To select one or more pictures from this box, click the left mouse
1332     button on a view name, and drag it up or down to select multiple
1333     views.
1334     Shift-click also allows views to be added to the selection.
1335    
1336     .Results.Unfinished
1337    
1338     The "Unfinished views" list box on the Results screen shows those
1339     renderings which have not yet completed.
1340     These partial pictures may or may not be out-of-date
1341     with respect to the Radiance input files.
1342     Select pictures in this box for display or deletion.
1343     It is not possible to convert or print an unfinished picture.
1344    
1345     To select one or more pictures from this box, click the left mouse
1346     button on a view name, and drag it up or down to select multiple
1347     views.
1348     Shift-click also allows views to be added to the selection.
1349    
1350     .Results.Rescan
1351    
1352 greg 2.3 The "Rescan" button on the Results screen is used to update the
1353     finished and unfinished view lists, in case one or more pictures
1354 greg 2.1 has completed since the Results screen was brought up.
1355    
1356     .Results.Delete
1357    
1358     The "Delete" button on the Results screen is used to remove the
1359     selected picture files from the filesystem.
1360 greg 2.14 Associated raw picture and z-buffer files
1361     will also be deleted if they exist.
1362 greg 2.1 Verification is required before any action is taken.
1363    
1364     .Results.Display
1365    
1366     The "Display" button on the Results screen may be used to display
1367     the selected images using ximage(1) or any other Radiance picture
1368     display program.
1369    
1370     The current display command is shown in the adjacent command window,
1371     and may be customized if necessary.
1372     (See the "DispCommand" topic in the current help category for
1373     details.)
1374    
1375     .Results.DispCommand
1376    
1377     The current display command in the Results screen determines how
1378     finished and unfinished Radiance pictures will be displayed.
1379     This command contains two variable fields.
1380     The first field is a signed integer, indicated by the "%+d" format.
1381     The second field is a string, indicated by the "%s" format.
1382     Both fields must appear in any display command used, and must be in
1383     this order on the command line.
1384     The first field is used to adjust the exposure of an unfinished
1385     picture, and the second field is the file name.
1386     The rest of the command is arbitrary, so long as it is understood by
1387     the system.
1388    
1389     The default command is "ximage -e %+d %s >& /dev/null &", which
1390     executes ximage in the background and sends any output (including
1391     error messages) to the null device.
1392     If you don't wish ximage to run in the background, you may remove
1393     the last part of the command (" >& /dev/null &").
1394    
1395     .Results.Convert
1396    
1397     The "Convert" button on the Results screen converts the selected
1398     pictures to the format indicated on the menu button to the right.
1399     (See the "ConvType" topic under the current help category for
1400     details.)
1401    
1402     Each finished picture is converted to the selected format and given
1403     the name indicated by the adjacent window labeled "File".
1404     (See the "ConvFile" topic under the current help category for
1405     details.)
1406    
1407     .Results.ConvType
1408    
1409     The image type button on the Results screen determines the
1410     destination format for converted Radiance pictures.
1411     You may choose from the list that pops up when you press this
1412     button.
1413     Often, a given format may have more than one subtype.
1414     In general, 8-bit means 8-bit color with a lookup table,
1415     B&W means 8-bit greyscale with no lookup, and 24-bit means 24-bit
1416     true color.
1417    
1418     The file suffix is determined by the basic conversion type, but may
1419     be changed along with the rest of the name by editing the file name
1420     window.
1421     (See the "ConvFile" topic under the current help category for
1422     details.)
1423    
1424     .Results.ConvFile
1425    
1426     The image conversion file name window on the Results screen should contain
1427     a single "%s" format field, which will be replaced by the view name
1428     being converted.
1429    
1430     The default name is the same as the value of the rad "PICTURE"
1431     variable, followed by a suffix appropriate to the selected file type.
1432    
1433     .Results.Print
1434    
1435     The "Print" button on the Results screen executes the given
1436     system command to print one copy each of the selected picture(s).
1437     This button does not work on unfinished pictures.
1438    
1439     The actual command used for printing may be edited in the adjacent
1440     window.
1441     (See the "PrintCommand" topic under the current help category for
1442     details.)
1443    
1444     .Results.PrintCommand
1445    
1446     The print command window on the Results screen contains the system
1447     command to use in printing out finished Radiance pictures.
1448     The "%s" format field, which must appear somewhere in the command,
1449 greg 2.15 is replaced by the selected Radiance picture file name.
1450     This command is executed multiple times if multiple files are
1451     selected.
1452 greg 2.1
1453     The default command is "ra_ps %s | lpr", which converts the Radiance
1454     picture to a black and white PostScript file and sends it to the lpr
1455     print spooler.
1456 greg 2.15 Add a "-c" option to "ra_ps" if the printer supports color.
1457 greg 2.1 If your printer does not understand PostScript, or your system does
1458     not support lpr, this command must obviously be changed.