honeybee_radiance_command.options.rcontrib module¶

class honeybee_radiance_command.options.rcontrib.RcontribOptions[source]¶

Bases: RtraceOptions

rcontrib command options.

[ -n nprocs ][ -V ][ -c count ][ -fo | -r ][ -e expr ][ -f source ][ -o ospec ] [ -p p1=V1,p2=V2][ -b binv ][ -bn nbins ] { -m mod | -M file } [ $EVAR ] [ @file ] [ rtrace options ]

Note: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/rcontrib.pdf

adjust_limit_weight()¶: Adjust lw to be 1 / ad if the value is larger than 1 / ad.

classmethod direct_studies()¶

Options for direct studies.

In particular this classmethod will set options below: irradiance_calc (-I) = True ambient_bounces (-ab) = 0 direct_certainty (-dc) = 1 direct_threshold (-dt) = 0 direct_jitter (-dj) = 0 direct_sec_relays (-dr) = 0

to_file(folder, file_name, mkdir=False)¶: Write options to a file.

to_radiance()[source]¶: Translate options to Radiance format.

update_from_string(string)¶

Update options from a standard radiance string.

If the option is not currently part of the collection, it will be added to additional_options.

property I¶

off

Boolean switch to compute irradiance rather than radiance, with the input origin and direction interpreted instead as measurement point and orientation.

For understanding the difference between -i and -I see here: https://discourse.radiance-online.org/t/rtrace-i-i-flags/4192/3

Type:: Irradiance calculation switch - default

property M¶

Modifiers file.

A modifier list may be read from a file using the -M option. The RAYPATH environment variable determines directories to search for this file. (No search takes place if a file name begins with a ., / or ~ character.)

property V¶

off = coefficients

By setting the boolean -V option, you may instruct rcontrib to report the contribution from each material rather than the ray coefficient. This is particularly useful for light sources with directional output distributions, whose value would otherwise be lost in the shuffle.

With the default -V- setting, the output of rcontrib is a coefficient that must be multiplied by the radiance of each material to arrive at a final contribution.

This is more convenient for computing daylight coefficients, or cases where the actual radiance is not desired. Use the -V+ setting when you wish to simply sum together contributions (with possible adjustment factors) to obtain a final radiance value. Combined with the -i or -I option, irradiance contributions are reported by -V+ rather than radiance, and -V- coefficients contain an additional factor of PI.

Type:: Output contribution versus coefficients - default

property aE¶

Append modifier to the ambient exclude list from file.

Same as -ae, except read modifiers to be excluded from file. The RAYPATH environment variable determines which directories are searched for this file. The modifier names are separated by white space in the file.

property aI¶

Add modifier to the ambient include list from file.

Same as -ai, except read modifiers to be included from file.

property aa¶

0.100000

Number of ambient accuracy. This value will approximately equal the error from indirect illuminance interpolation. A value of zero implies no interpolation.

Type:: Ambient accuracy - default

property ab¶

Number of ambient bounces. This is the maximum number of diffuse bounces computed by the indirect calculation. A value of zero implies no indirect calculation.

Type:: Ambient bounces - default

property ad¶

1024

Number of ambient divisions. The error in the Monte Carlo calculation of indirect illuminance will be inversely proportional to the square root of this number. A value of zero implies no indirect calculation.

Type:: Ambient divisions - default

additional_options¶

property ae¶

Append modifier to the ambient exclude list.

So that it will not be considered during the indirect calculation. This is a hack for speeding the indirect computation by ignoring certain objects. Any object having mod as its modifier will get the default ambient level rather than a calculated value. Any number of excluded modifiers may be given, but each must appear in a separate option.

property af¶

Set the ambient file to filename.

This is where indirect illuminance will be stored and retrieved. Normally, indirect illuminance values are kept in memory and lost when the program finishes or dies. By using a file, different invocations can share illuminance values, saving time in the computation. The ambient file is in a machine-independent binary format which can be examined with lookamb.

The ambient file may also be used as a means of communication and data sharing between simultaneously executing processes. The same file may be used by multiple processes, possibly running on different machines and accessing the file via the network (ie. nfs(4)). The network lock manager lockd(8) is used to insure that this information is used consistently.

If any calculation parameters are changed or the scene is modified, the old ambient file should be removed so that the calculation can start over from scratch. For convenience, the original ambient parameters are listed in the header of the ambient file. Getinfo(1) may be used to print out this information.

property ai¶

Add modifier to the ambient include list.

So that it will be considered during the indirect calculation. The program can use either an include list or an exclude list, but not both.

property ap¶

Photon map generated file.

Rcontrib supports light source contributions from photon maps generated by mkpmap with its -apC option. Enabling photon mapping is described in the rtrace man page along with its relevant settings. In photon mapping mode, rcontrib only supports contributions from light sources, not arbitrary modifiers.

property ar¶

256

This number will determine the maximum density of ambient values used in interpolation. Error will start to increase on surfaces spaced closer than the scene size divided by the ambient resolution. The maximum ambient value density is the scene size times the ambient accuracy.

Type:: Ambient resolution - default

property as_¶

512

Number of ambient super-samples. Super-samples are applied only to the ambient divisions which show a significant change.

Type:: Ambient super-samples - default

property av¶

0.000000 0.000000 0.000000

Set the ambient value to a radiance of red grn blu . This is the final value used in place of an indirect light calculation. If the number of ambient bounces is one or greater and the ambient value weight is non-zero (see -aw and -ab below), this value may be modified by the computed indirect values to improve overall accuracy.

Type:: Ambient value - default

property aw¶

Set the relative weight of the ambient value given with the -av option. As new indirect irradiances are computed, they will modify the default ambient value in a moving average, with the specified weight assigned to the initial value given on the command and all other weights set to 1. If a value of 0 is given with this option, then the initial ambient value is never modified. This is the safest value for scenes with large differences in indirect contributions, such as when both indoor and outdoor (daylight) areas are visible.

Type:: Ambient value weight - default

property b¶

Bin numbers.

The -b option may be used to further define a “bin number” within each object if finer resolution is needed, and this will be applied to a “%d” format in the output file specification if present. (The final integer will be offset incrementally if the output is a RADIANCE picture and more than one modifier has the same format specification.) The actual bin number is computed at run time based on ray direction and surface intersection.

property bn¶

Number of bins.

The number of bins must be specified in advance with the -bn option, and this is critical for output files containing multiple values per record. A variable or constant name may be given for this parameter if it has been defined via a previous -f or -e option. Since bin numbers start from zero, the bin count is always equal to the last bin plus one. The most recent -p, -b, -bn and -o options to the left of each -m setting are the ones used for that modifier.

property bv¶

Boolean switch for back face visibility. With this switch off, back faces of opaque objects will be invisible to all rays. This is dangerous unless the model was constructed such that all surface normals on opaque objects face outward. Although turning off back face visibility does not save much computation time under most circumstances, it may be useful as a tool for scene debugging, or for seeing through one-sided walls from the outside. This option has no effect on transparent or translucent materials.

Type:: Back face visibility - default

property c¶

The -c option tells rcontrib how many rays to accumulate for each record. The default value is one, meaning a full record will be produced for each input ray. For values greater than one, contributions will be averaged together over the given number of input rays.

If set to zero, only a single record will be produced at the very end, corresponding to the sum of all rays given on the input (rather than the average). This is equivalent to passing all the output records through a program like total to sum RGB values together, but is much more efficient. Using this option, it is possible to reverse sampling, sending rays from a parallel source such as the sun to a diffuse surface, for example. Note that output flushing via zero-direction rays is disabled with -c set to zero.

Type:: Accumulated rays per record - default

property command¶: Command name.

property dc¶

0.750000

Set the direct certainty to frac. A value of one guarantees that the absolute accuracy of the direct calculation will be equal to or better than that given in the -dt specification. A value of zero only insures that all shadow lines resulting in a contrast change greater than the -dt specification will be calculated.

Type:: Direct certainty - default

property dj¶

0.000000

Set the direct jittering to frac. A value of zero samples each source at specific sample points (see the -ds option below), giving a smoother but somewhat less accurate rendering. A positive value causes rays to be distributed over each source sample according to its size, resulting in more accurate penumbras. This option should never be greater than 1, and may even cause problems (such as speckle) when the value is smaller. A warning about aiming failure will issued if frac is too large. It is usually wise to turn off image sampling when using direct jitter by setting -ps to 1.

Type:: Direct jitter - default

property dp¶

512

Set the secondary source presampling density to D. This is the number of samples per steradian that will be used to determine ahead of time whether or not it is worth following shadow rays through all the reflections and/or transmissions associated with a secondary source path. A value of 0 means that the full secondary source path will always be tested for shadows if it is tested at all.

Type:: Direct pretest density - default

property dr¶

Set the number of relays for secondary sources to N. A value of 0 means that secondary sources will be ignored. A value of 1 means that sources will be made into first generation secondary sources; a value of 2 means that first generation secondary sources will also be made into second generation secondary sources, and so on.

Type:: Direct relays - default

property ds¶

0.200000

Set the direct sampling ratio to frac. A light source will be subdivided until the width of each sample area divided by the distance to the illuminated point is below this ratio. This assures accuracy in regions close to large area sources at a slight computational expense. A value of zero turns source subdivision off, sending at most one shadow ray to each light source.

Type:: Direct sampling - default

property dt¶

0.030000

Set the direct threshold to frac. Shadow testing will stop when the potential contribution of at least the next and at most all remaining light source samples is less than this fraction of the accumulated value. The remaining light source contributions are approximated statistically. A value of zero means that all light source samples will be tested for shadow.

Type:: Direct threshold - default

property dv¶

Boolean switch for light source visibility. With this switch off, sources will be black when viewed directly although they will still participate in the direct calculation. This option is mostly for the program mkillum to avoid inappropriate counting of light sources, but it may also be desirable in conjunction with the -i option.

Type:: Direct visibility - default

property e¶

Expression.

The -e expr option can be used to define variables on the command line. Since many of the characters in an expression have special meaning to the shell, it should usually be enclosed in single quotes.

property f¶: Source file.

property fio¶

faa

Format input according to the character i and output according to the character o. Rtrace understands the following input and output formats - a for ascii - f for single-precision floating point - d for double-precision floating point

In addition to these three choices, the character c may be used to denote 4-byte floating point (Radiance) color format for the output of values only (-ov option, below). If the output character is missing, the input format is used.

Type:: Format input/output = ascii/ascii - default

property fo¶: Format output.

property h¶

Boolean switch for information header on output

Type:: Output header - default

property i¶

off

Boolean switch to compute irradiance rather than radiance values. This only affects the final result, substituting a Lambertian surface and multiplying the radiance by pi. Glass and other transparent surfaces are ignored during this stage. Light sources still appear with their original radiance values, though the -dv option (below) may be used to override this. This option is especially useful in conjunction with ximage for computing illuminance at scene points.

Keep in mind that -i sends a ray into the scene and calculates the incident irradiance at that surface point. For calculating irradiance at the sensor point see -I.

For understanding the difference between -i and -I see here: https://discourse.radiance-online.org/t/rtrace-i-i-flags/4192/3

Type:: Irradiance calculation - default

property ld¶

off

Type:: Limit distance - default

property lr¶

-10

Limit reflections to a maximum of N, if N is a positive integer. If N is zero, then Russian roulette is used for ray termination, and the -lw setting (below) must be positive. If N is a negative integer, then this sets the upper limit of reflections past which Russian roulette will be used. In scenes with dielectrics and total internal reflection, a setting of 0 (no limit) may cause a stack overflow.

Type:: Limit reflection (Russian roulette) - default

property lw¶

2.00e-003

Limit the weight of each ray to a minimum of frac. During ray-tracing, a record is kept of the estimated contribution (weight) a ray would have in the image. If this weight is less than the specified minimum and the -lr setting (above) is positive, the ray is not traced. Otherwise, Russian roulette is used to continue rays with a probability equal to the ray weight divided by the given frac.

Type:: Limit weight - default

property m¶: Modifier name.

property ma¶

0.000000 0.000000 0.000000

Set the global medium albedo to the given value between 0 0 0 and 1 1 1. A zero value means that all light not transmitted by the medium is absorbed. A unitary value means that all light not transmitted by the medium is scattered in some new direction. The isotropy of scattering is determined by the Heyney-Greenstein parameter, described below.

Type:: Mist scattering albedo - default

property me¶

0.00e+000 0.00e+000 0.00e+000

Set the global medium extinction coefficient to the indicated color, in units of 1/distance (distance in world coordinates). Light will be scattered or absorbed over distance according to this value. The ratio of scattering to total scattering plus absorption is set by the albedo parameter, described below.

Type:: Mist extinction coefficient - default

property mg¶

0.000000

Set the medium Heyney-Greenstein eccentricity parameter. This parameter determines how strongly scattering favors the forward direction. A value of 0 indicates perfectly isotropic scattering. As this parameter approaches 1, scattering tends to prefer the forward direction.

Type:: Mist scattering eccentricity - default

property ms¶

0.000000

Set the medium sampling distance, in world coordinate units. During source scattering, this will be the average distance between adjacent samples. A value of 0 means that only one sample will be taken per light source within a given scattering volume.

Type:: Mist sampling distance - default

property n¶

Execute in parallel on nproc local processes.

Note:

This option is incompatible with the -P and -PP, options. Multiple processes also do not work properly with ray tree output using any of the -o*t* options. There is no benefit from specifying more processes than there are cores available on the system or the -x setting, which forces a wait at each flush.

Type:: Number of rendering processes - default

property o¶

ov -o[spec]

Produce output fields according to spec. Characters are interpreted as follows: o - origin (input) d - direction (normalized) v - value (radiance) V - contribution (radiance) w - weight W - color coefficient l - effective length of ray L - first intersection distance c - local (u,v) coordinates p - point of intersection n - normal at intersection (perturbed) N - normal at intersection (unperturbed) s - surface name m - modifier name M - material name ~ tilde (end of trace marker) If the letter t appears in spec, then the fields following will be printed for every ray traced, not just the final result. If the capital letter T is given instead of t, then all rays will be reported, including shadow testing rays to light sources. Spawned rays are indented one tab for each level. The tilde marker (~) is a handy way of differentiating the final ray value from daughter values in a traced ray tree, and usually appears right before the t or T output flags. E.g., -ov~TmW will emit a tilde followed by a tab at the end of each trace, which can be easily distinguished even in binary output.

Type:: Output value - default

property options¶: Print out list of options.

property p¶: Additional parameters.

property r¶: Data recovery.

property slots¶: Return slots including the ones from the baseclass if any.

property ss¶

1.000000

Set the specular sampling to samp. For values less than 1, this is the degree to which the highlights are sampled for rough specular materials. A value greater than one causes multiple ray samples to be sent to reduce noise at a commmesurate cost. A value of zero means that no jittering will take place, and all reflections will appear sharp even when they should be diffuse. This may be desirable when used in combination with image sampling to obtain faster renderings.

Type:: Specular sampling - default

property st¶

0.150000

Set the specular sampling threshold to frac. This is the minimum fraction of reflection or transmission, under which no specular sampling is performed. A value of zero means that highlights will always be sampled by tracing reflected or transmitted rays. A value of one means that specular sampling is never used. Highlights from light sources will always be correct, but reflections from other surfaces will be approximated using an ambient value. A sampling threshold between zero and one offers a compromise between image accuracy and rendering time.

Type:: Specular threshold - default

property t¶: Optional interval in seconds to report the progress.

property tE¶

Append modifier to the trace exclude list from file.

Same as -te, except read modifiers to be excluded from file. The RAYPATH environment variable determines which directories are searched for this file. The modifier names are separated by white space in the file.

property tI¶

Add modifier to the trace include list from file.

Same as -ti, except read modifiers to be included from file.

property te¶

Append modifier to the trace exclude list.

The excluded modifier will not be reported by the trace option -o*t*. Any ray striking an object having mod as its modifier will not be reported to the standard output with the rest of the rays being traced. This option has no effect unless either the t or T option has been given as part of the output specifier. Any number of excluded modifiers may be given, but each must appear in a separate option.

property ti¶

Add modifier to the trace include list.

Add modifier to the trace include list, so that it will be reported by the trace option. The program can use either an include list or an exclude list, but not both.

property u¶

Boolean switch to control uncorrelated random sampling. When “off”, a low-discrepancy sequence is used, which reduces variance but can result in a brushed appearance in specular highlights. When “on”, pure Monte Carlo sampling is used in all calculations.

Type:: Uncorrelated Monte Carlo sampling - default

property w¶

Type:: Warning messages - default

property x¶

Set the x resolution to res. The output will be flushed after every res input rays if -y is set to zero. A value of one means that every ray will be flushed, whatever the setting of -y. A value of zero means that no output flushing will take place.

Type:: Flush interval - default

property y¶

Set the y resolution to res. The program will exit after res scanlines have been processed, where a scanline is the number of rays given by the -x option, or 1 if -x is zero. A value of zero means the program will not halt until the end of file is reached.

If both -x and -y options are given, a resolution string is printed at the beginning of the output. This is mostly useful for recovering image dimensions with pvalue, and for creating valid Radiance picture files using the color output format. (See the -f option, above.)

Type:: Y resolution - default