Keywords: main

Next: 2.9 Scene Example Up: 2. Scene Description Language Previous: 2.7 Scene Entities
Subsections

- 2.8.1 Where to Place Contours
- 2.8.2 Color and Width of Contours
- 2.8.3 Contour Output
- 2.8.4 Faster Contours

# 2.8 Contours

In order to get contours, it is necessary to link with the `contour.so` shader library, and a `$include <contour.mi>` statement is also needed. The file `contour.mi` contains declarations of the contour shaders in `contour.so`.

Also, the contour store shader has to be specified in the `options` statement. A contour store shader has no parameters and is specified as

         contour store "contour_store_function" ()

## 2.8.1 Where to Place Contours

A contour contrast shader specifies where there should be a contour. Like the contour store shader, the contour contrast function has to be specified in the `options` statement. The parameters of this function specify which difference in depth or surface orientation should cause a contour. For example, to get a contour where the difference in depth is more than 1.0 or the difference in surface normal is more than 60 degrees and between materials, the following contour contrast shader is used

         contour contrast "contour_contrast_function_levels" (
            "zdelta"     1.0,
            "ndelta"     60.0,
            "diff_mat"   on,
            "contrast"   on,
            "min_level"  1,
            "max_level"  1
         )

(Be aware that if `zdelta` or `ndelta` is set to a very small value, contours will be created also in large regions interior to objects.)

When `diff_mat` is `on`, contours are created between different materials. When `contrast` is `on`, contours are created where the contrast between colors is larger than the `contrast` specified in the options within the `options` statement. The parameters `min_level` and `max_level` tell which levels of reflection and layers of semitransparent materials should have contours on them. When both are set to 1, as here, only the outermost materials get contours and no reflections cause contours.

The hands in the figure shows the influence the parameters of the contour contrast shader has on where contours are created. Top row (left to right): large `zdelta` and `ndelta` give only contours on the outline where the depth difference to the infinitely distant background is large; large `ndelta` and small `zdelta` give contours where there is even a small depth difference; small `ndelta` and `zdelta` gives contours where there is a small change in depth or orientation. Bottom row: Contours on deeper levels of materials seen through a semitransparent material; contours on reflections on a reflective material, for example the reflection of the thumb is visible in the index finger.

## 2.8.2 Color and Width of Contours

The contour properties (color, width, etc.) depend on the object the contour is on and its material. For each material that should have a contour, one has to specify a contour shader. A material will not get a contour if it does not have a contour shader. The colors consist of four components: red, green, and blue color, and opacity. All four components of the color are normally between 0 and 1. The width is specified as a percentage of the minimum of image x resolution and y resolution. For example, if the image resolution is 700 `x` 500 and a contour width of 1.0 (percent) is specified, the thickness of the line becomes 5 pixels. The color, width, etc. can be parameters, or depend on curvature, distance, color, and illumination.

A material gets a simple contour of constant color and width if it has the `contour_shader_simple` contour shader. For example, the following specifies red contours that are half a percent wide:

         contour "contour_shader_simple" (
            "color"  1.0 0.0 0.0 1.0,   # solid red
            "width"  0.5                # in % of image resol
         )

As another example of a contour shader, contours of color and width that are linearly interpolated between two values, depending on distance to the camera, are specified with the contour shader `contour_shader_depthfade`. Two depths, colors, and widths are specified. If a contour point is more distant than `far_z`, the contour gets color `far_color` and width `far_width`. If a point is nearer than `near_z`, the contour gets color `near_color` and width `near_width`. If the depth is in between, the color and width are linearly interpolated. For example, to get contours that are interpolated between two percent wide red at depth -10 and half a percent wide blue at depth -25, specify

         contour "contour_shader_depthfade" (
            "near_z"     -10.0,             # from this depth,
            "near_color"  1.0 0.0 0.0 1.0,  # color (red),
            "near_width"  2.0,              # and width (in %)
            "far_z"      -25.0,             # to this depth,
            "far_color"   0.0 0.0 1.0 1.0,  # color (blue),
            "far_width"   0.5               # and width (in %)
         )

The left figure is a black-and-white illustration of this depthfade contour shader. The right figure is a scene with two materials with different contour type: illumination-dependent contours on the teapot and simple contours on the ``floor''.

There are many other contour shaders in `contour.so`, and new ones can be written by the user.

## 2.8.3 Contour Output

After the regular image has been computed, a contour output shader can get the contour line segments and use them to for example render a contour image or write a file with contour information. The user can write contour output shaders using the built-in function mi_get_contour_line.

There are three contour output shaders in `contour.so`. They can generate a contour image, a contour image composited over the regular image, and a PostScript file with black contours. The output shader has to be specified in the `camera`.

To get a contour image called `mycontourimage.rgb` in `rgb` format, write

         output "contour,rgba" "contour_only" ()
         output "rgb" "mycontourimage.rgb"

To get an image called `mycontourimage2.rgb` (in `rgb` format) containing contours composited over the regular image, write

         output "contour,rgba" "contour_composite" ()
         output "rgb" "mycontourimage2.rgb"

The `contour_composite` output shader has two optional Boolean parameters: `glow` and `maxcomp`. The `glow` parameter makes all contours become darker and more transparent near their edges, creating a glow effect. `maxcomp` specifies that when a contour is over another contour, the maximum of the two colors (in each color band) should be used. If `maxcomp` is not specified (or set `off`), normal alpha compositing is used. The `contour_only` output shader also has the `glow` and `maxcomp` parameters, and in addition it has a `background` parameter which determines the background color (default is black).

To get a PostScript file called `mycontourfile.ps` with all contours in black, write

         output "contour,rgba" "contour_ps" (
            "paper_size"         4,
            "paper_scale"        1.0,
            "paper_transform_b"  0.0,
            "paper_transform_d"  1.0,
            "title"              on,
            "landscape"          on,
            "ink_stroke_dir"     1.0 1.0 0.0,
            "ink_min_frac"       0.1,
            "file_name"          "mycontourfile.ps"
         )

The PostScript file in this example gives A4 paper size with full scale. `"paper_size"` is an integer, with 0 indicating ``letter'' size, 1 indicating ``executive'', 2 indicating ``legal'', 3-6 indicating ``a3'', ``a4'', ``a5'', ``a6'', 7-9 indicating ``b4'', ``b5'', ``b6'', and 10 indicating ``11x17''. The parameter `paper_scale` scales the PostScript output. Furthermore, the Postscript coordinates are transformed according to the matrix (1 b, 0 d), where b and d are the parameters `"paper_transform_b"` and `"paper_transform_d"`. This e.g. enables one to compensate for printers that print out with a slight skew. The Boolean `title` determines whether a title (consisting of file name and frame number) and a frame around the image are written. The Boolean `landscape` makes the output be in landscape mode rather than portrait mode. If the parameter `ink_stroke_dir` is set, each contour segment will have a width that depends on its orientation, giving an ink pen look. For the ink pen look, `ink_min_frac` specifies the minimum fraction of the original contour thickness (at contour segment orientations perpendicular to the stroke direction). The `file_name` specifies the name of the file that the contours are written to.

It is also possible to get both the regular image (without contours) and one of the above at the same time. For example, to get the regular image and an image of the contours, write

         output "rgb" "myimage.rgb"
         output "contour,rgba" "contour_only" ()
         output "rgb" "mycontourimage.rgb"

## 2.8.4 Faster Contours

If only simple outlines of objects are needed, contour_shader_simple can be used with contour_store_function_simple and contour_contrast_function_simple to get fast contour computations. Furthermore, very simple material shaders should be used (no illumination, shadow, reflection, refraction, or texture computations).

Next: 2.9 Scene Example Up: 2. Scene Description Language Previous: 2.7 Scene Entities