ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/util/trad.hlp
Revision: 2.2
Committed: Fri Oct 28 11:09:52 1994 UTC (29 years, 5 months ago) by greg
Branch: MAIN
Changes since 2.1: +1 -3 lines
Log Message:
correction about loading bad RIF

File Contents

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