Documentation Talk:Reference Section 3.1

From POV-Wiki
Jump to navigation Jump to search

Global Settings

The global_settings statement is a catch-all statement that gathers together a number of global parameters. The statement may appear anywhere in a scene as long as it is not inside any other statement. You may have multiple global_settings statements in a scene. Whatever values were specified in the last global_settings statement override any previous settings.

Note: some items which were language directives in earlier versions of POV-Ray have been moved inside the global_settings statement so that it is more obvious to the user that their effect is global. The old syntax is permitted but generates a warning.

The new syntax is:

GLOBAL_SETTINGS:
  global_settings { [GLOBAL_SETTINGS_ITEMS...] }
GLOBAL_SETTINGS_ITEM:
  adc_bailout Value | ambient_light COLOR | assumed_gamma Value | 
  file_gamma Value | hf_gray_16 [Bool] | irid_wavelength COLOR |
  charset GLOBAL_CHARSET | max_intersections Number |
  max_trace_level Number | number_of_waves Number |
  noise_generator Number | radiosity { RADIOSITY_ITEMS... } |
  photon { PHOTON_ITEMS... }
GLOBAL_CHARSET:
  ascii | utf8 | sys

Global setting default values:

charset		   : ascii
adc_bailout	   : 1/255
ambient_light	   : <1,1,1>
assumed_gamma	   : deprecated
file_gamma	   : sRGB
hf_gray_16	   : deprecated
irid_wavelength	   : <0.25,0.18,0.14>
max_trace_level	   : 5
max_intersections  : 64
number_of_waves	   : 10
noise_generator	   : 2

Radiosity:
adc_bailout	   : 0.01
always_sample	   : on
brightness	   : 1.0
count		   : 35  (max = 1600)
error_bound	   : 1.8
gray_threshold	   : 0.0
low_error_factor   : 0.5
max_sample	   : non-positive value
minimum_reuse	   : 0.015
nearest_count	   : 5   (max = 20)
normal		   : off 
pretrace_start	   : 0.08
pretrace_end	   : 0.04
recursion_limit	   : 3

Each item is optional and may appear in any order. If an item is specified more than once, the last setting overrides previous values. Details on each item are given in the following sections.

Assumed_Gamma

The way POV-Ray 3.7 handles the assumed_gamma keyword has changed! Previously the presence of this keyword in global_settings caused a possible error warning and its presence was ignored. In addition no gamma correction was available in previous versions. Starting with version 3.7 however, gamma correction is performed on both the display and file output, subject to the following criteria:

  • If the scene language version is set to 3.7 (or not set at all), then gamma correction will default to ON, with the value used being set by the display_gamma INI file setting.

    Note: that in previous versions of POV-Ray gamma correction was OFF by default but otherwise this is the same.

  • If the scene language version is set to earlier than 3.7, then gamma will be OFF by default.
  • Notwithstanding the above, if the keyword assumed_gamma is present in the scene's global_settings, then POV will take one of the following actions:
    • If assumed_gamma 2.2 is present, gamma correction will be turned OFF and a warning issued. the same thing will happen if the value specified is not 2.2 but happens to be the default for the platform setting given to POV-Ray when it was compiled (e.g. Windows is 2.2).
    • If assumed_gamma 1.0 is present, gamma correction will be turned ON (if it's not already on) and in any case a warning will be issued.
    • If a value other than the above is specified, it is ignored and a possible error message is issued.

You will note from the above that therefore it is no longer possible to adjust the amount of gamma correction from a scene file. This is as designed since scene files should be as much as possible be platform independent, and the gamma of particular display hardware does not belong in the scene file. If you really need to specify assumed_gamma you can do so in an INI file or on the command-line; however in those cases you may as well just use display_gamma in its place.

When writing file formats that support gamma specification, the inverse of the assumed_gamma value will be embedded in the file headers, so that an appropriately equipped display program can 'undo' the gamma correction if it is so desired. This is as per previous versions of POV-Ray.

With POV-Ray 3.7, it is strongly recommended to work without assumed_gamma and set file_gamma 2.2 in the scene's global_settings for any image you plan to share with others.

Monitor Gamma

The differences in how images are displayed is a result of how a computer actually takes an image and displays it on the monitor. In the process of rendering an image and displaying it on the screen, several gamma values are important, including the POV scene file or image file gamma and the monitor gamma.

Most image files generated by POV-Ray store numbers in the range from 0 to 255 for each of the red, green and blue components of a pixel. These numbers represent the intensity of each color component, with 0 being black and 255 being the brightest color (either 100% red, 100% green or 100% blue). When an image is displayed, the graphics card converts each color component into a voltage which is sent to the monitor to light up the red, green and blue phosphors on the screen. The voltage is usually proportional to the value of each color component.

Gamma becomes important when displaying intensities that are not the maximum or minimum possible values. For example, 127 should represent 50% of the maximum intensity for pixels stored as numbers between 0 and 255. On systems that do not do gamma correction, 127 will be converted to 50% of the maximum voltage, but because of the way the phosphors and the electron guns in a monitor work, this may be only 22% of the maximum color intensity on a monitor with a gamma of 2.2. To display a pixel which is 50% of the maximum intensity on this monitor, we would need a voltage of 73% of the maximum voltage, which translates to storing a pixel value of 186.

The relationship between the input pixel value and the displayed intensity can be approximated by an exponential function obright = ibright ^ display_gamma where obright is the output intensity and ibright is the input pixel intensity. Both values are in the range from 0 to 1 (0% to 100%). Most monitors have a fixed gamma value in the range from 1.8 to 2.6. Using the above formula with display_gamma values greater than 1 means that the output brightness will be less than the input brightness. In order to have the output and input brightness be equal an overall system gamma of 1 is needed. To do this, we need to gamma correct the input brightness in the same manner as above but with a gamma value of 1/display_gamma before it is sent to the monitor. To correct for a display gamma of 2.2, this pre-monitor gamma correction uses a gamma value of 1.0/2.2 or approximately 0.45.

How the pre-monitor gamma correction is done depends on what hardware and software is being used. On Macintosh systems, the operating system has taken it upon itself to insulate applications from the differences in display hardware. Through a gamma control panel the user may be able to set the actual monitor gamma and Mac will then convert all pixel intensities so that the monitor will appear to have the specified gamma value. On Silicon Graphics machines, the display adapter has built-in gamma correction calibrated to the monitor which gives the desired overall gamma (the default is 1.7). Unfortunately, on PCs and most UNIX systems, it is up to the application to do any gamma correction needed.

Image File Gamma

Since most PC and UNIX applications and image file formats do not understand display gamma, they do not do anything to correct for it. As a result, users creating images on these systems adjust the image in such a way that it has the correct brightness when displayed. This means that the data values stored in the files are made brighter to compensate for the darkening effect of the monitor. In essence, the 0.45 gamma correction is built in to the image files created and stored on these systems. When these files are displayed on a Macintosh system, the gamma correction built in to the file, in addition to gamma correction built into MacOS, means that the image will be too bright. Similarly, files that look correct on Macintosh or SGI systems because of the built-in gamma correction will be too dark when displayed on a PC.

The PNG format files generated by POV-Ray overcome the problem of too much or not enough gamma correction by storing the image file gamma (which is 1.0/display_gamma) inside the PNG file when it is generated by POV-Ray. When the PNG file is later displayed by a program that has been set up correctly, it uses this gamma value as well as the current display gamma to correct for the potentially different display gamma used when originally creating the image.

Unfortunately, of all the image file formats POV-Ray supports, PNG is the only one that has any gamma correction features and is therefore preferred for images that will be displayed on a wide variety of platforms.

Note: Non-legacy scene default gamma handling for image input files has changed significantly from previous versions, affecting all file formats except OpenEXR, Radiance HDR and (with minor differences) most flavors of PNG; there will be NO corresponding warnings. See below for more detail.

Input image files not carrying unambiguous gamma information will now be assumed to match a common gamma setting, and gamma-adjusted accordingly; this common input file gamma setting can be specified in the scene file using the following syntax:

global_settings {
  file_gamma GAMMA
  }

where GAMMA is either a numeric expression specifying the approximate display gamma for which input files are assumed to be gamma pre-corrected, or the keyword srgb indicating that input files are assumed to match the sRGB standard. (In the latter case, gamma adjustment is applied according to the sRGB standard, instead of approximating with a gamma 2.2 power-law function.) The default setting is sRGB.

Regardless of this global setting, gamma correction is not applied if the image input file is obviously used as a mere data container, such as when immediately used in a height field.

Default gamma handling rules for any image input file can be overridden by specifying file_gamma GAMMA immediately after the file name, e.g.:

image_map {
  jpeg "foobar.jpg" file_gamma 1.8
  interpolate 2
  }

This also applies to contexts where gamma adjustment is not normally applied, e.g. file formats that are defined to be encoded linearly, or files used in height fields, to simplify handling of files not conforming to standards.

Note: Gamma handling for PNG input files has changed as follows in legacy #version 3.6 scenes:

  1. In the absence of an assumed_gamma statement, non-indexed PNG files with a gAMA chunk (i.e. virtually all PNG files) will appear far brighter than with POV-Ray 3.6
  2. In the presence of an assumed_gamma 1.0 statement, indexed PNG files (uncommon) will appear darker than with POV-Ray 3.6
  3. In the presence of an assumed_gamma 2.2 statement, PNG files with a gAMA lower than 2.2 (uncommon) will appear darker than with POV-Ray 3.6
  4. PNG files with an sRGB chunk but no gAMA chunk may appear significantly different than with POV-Ray 3.6
  5. PNG files may generally appear slightly different than with POV-Ray 3.6

A warning will be printed in these cases, except for the latter.

Scene File Gamma

The image file gamma problem itself is just a result of how scenes themselves are generated in POV-Ray. When you start out with a new scene and are placing light sources and adjusting surface textures and colors, you generally make several attempts before the lighting is how you like it. How you choose these settings depends upon the preview image or the image file stored to disk, which in turn is dependent upon the overall gamma of the display hardware being used.

This means that as the artist you are doing gamma correction in the POV-Ray scene file for your particular hardware. This scene file will generate an image file that is also gamma corrected for your hardware and will display correctly on systems similar to your own. However, when this scene is rendered on another platform, it may be too bright or too dim, regardless of the output file format used. Rather than have you change all the scene files to have a single fixed gamma value, POV-Ray allows you to specify in the scene file the display gamma of the system that the scene was created on.

The file_gamma global setting, in conjunction with the Display_Gamma INI setting lets POV-Ray know how to do gamma correction on a given scene so that the preview and output image files will appear the correct brightness on any system. Since the gamma correction is done internally to POV-Ray, it will produce output image files that are the correct brightness for the current display, regardless of what output format is used.

HF_Gray_16

Grayscale output can be used to generate heightfields for use in other POV-Ray scenes, and may be specified via Grayscale_Output=true as an INI option, or +Fxg (for output type 'x') as a command-line option. For example, +Fng for PNG and +Fpg for PPM (effectively PGM) grayscale output. By default this option is off.

Note: In version 3.7 the hf_gray_16 keyword in the global_settings block has been deprecated. If encountered, it has no effect on the output type and will additionally generate a warning message.

With Grayscale_Output=true, the output file will be in the form of a heightfield, with the height at any point being dependent on the brightness of the pixel. The brightness of a pixel is calculated in the same way that color images are converted to grayscale images: height = 0.3 * red + 0.59 * green + 0.11 * blue.

Setting the Grayscale_Output=true option will cause the preview display, if used, to be grayscale rather than color. This is to allow you to see how the heightfield will look because some file formats store heightfields in a way that is difficult to understand afterwards. See section "Height Field" for a description of how POV-Ray heightfields are stored for each file type.

Caveat: grayscale output implies the maximum bit-depth the format supports is 16, it is not valid to specify bits per color channel with 'g' (e.g. +Fng16 is not allowed, and nor for that matter is +Fn16g). If bits per channel is provided via an INI option, it is ignored.

Currently PNG, and PPM are the only file formats that support grayscale output.

Retrieved from "https://wiki.povray.org/content?title=Documentation_Talk:Reference_Section_3.1&oldid=2477"