doc/salome/gui/GEOM/input/material.doc

   1 /*!
   2
   3 \page material_page Material properties
   4
   5 \tableofcontents
   6
   7 \section material_general_description General description
   8
   9 \note The functionality related to the material properties is
  10 \b experimental, so it might work not as expected. The behaviour might
  11 be changed in the future versions of SALOME Geometry module.
  12
  13 \n You can change the material properties of the selected shape(s) in
  14 the dedicated dialog box. This dialog box can be invoked from the
  15 context popup menu using "Material properties" item:
  16
  17 \image html material.png
  18
  19 In this dialog box you can:
  20 - modify the properties of the material model currenly assigned to the
  21 shape presentation;
  22 - assign one of predefined global materials to the shape;
  23 - create a custom material model and apply it to the shape.
  24
  25 \note This functionality is available in both OCC and VTK 3D
  26 viewers. However, note that due to the differencies between underlying API
  27 of OCC and VTK libraries the behaviour of the functionality related to
  28 the materials is different:
  29 - presentation of the shape in OCC and VTK viewers is not fully identical;
  30 - some material attributes can affect presentation in a different way.
  31
  32 \section material_opengl_model OpenGL ligthing model
  33
  34 The material is specifed by several attributes of the lighting
  35 model. More details can be found in the documentation related to the
  36 OpenGL programming, for example here: http://www.glprogramming.com/red/chapter05.html.
  37
  38 In the OpenGL lighting model, the light in a scene comes from several
  39 light sources; the light sources have an effect only when there are
  40 surfaces that absorb and reflect light. Each surface is assumed to be
  41 composed of a material with various properties. A material might emit
  42 its own light (like headlights on an automobile), it might scatter
  43 some incoming light in all directions, and it might reflect a
  44 portion of the incoming light in a preferential direction like a
  45 mirror or other shiny surface.
  46
  47 The OpenGL lighting model considers the lighting to be divided into
  48 four independent components: emissive, ambient, diffuse, and
  49 specular. All four components are computed independently and then
  50 added together.
  51
  52 Ambient illumination is the light that has been scattered so much by the
  53 environment that its direction is impossible to determine - it seems
  54 to come from all directions. Backlighting in a room has a large
  55 ambient component, since most of the light that reaches your eye has
  56 first bounced off many surfaces. A spotlight outdoors has a tiny
  57 ambient component; most of the light travels in the same direction,
  58 and since you're outdoors, very little of the light reaches your eye
  59 after bouncing off other objects. When ambient light strikes a
  60 surface, it is scattered equally in all directions.
  61
  62 The diffuse component is the light that comes from one direction, so
  63 it is brighter if it comes squarely down on a surface than if it barely
  64 glances off the surface. Once it hits a surface, however, it's
  65 scattered equally in all directions, so it appears equally bright, no
  66 matter where the eye is located. Any light coming from a particular
  67 position or direction probably has a diffuse component.
  68
  69 Finally, the specular light comes from a particular direction, and it
  70 tends to bounce off the surface in a preferred direction. A
  71 well-collimated laser beam bouncing off a high-quality mirror produces
  72 specular reflection by almost 100 percent. Shiny metal or plastic has a
  73 high specular component, and chalk or carpet has almost none. You can
  74 think of specularity as shininess.
  75
  76 Although a light source delivers a single distribution of frequencies,
  77 the ambient, diffuse, and specular components might be different. For
  78 example, if you have a white light in a room with red walls, the
  79 scattered light tends to be red, although the light directly striking
  80 objects is white. OpenGL allows you to set the red, green, and blue
  81 values for each component of light independently.
  82
  83 \section material Material properties dialog box
  84
  85 The dialog box consists of two parts:
  86 - The list box at the left shows all available material models, both
  87 predefined by the application and custom one specified by the user.
  88 - The widgets in the right part of the dialog box allows modifyng of
  89 different properties of the material model.
  90
  91 The following properties of the material model can be specified:
  92 - \b Ambient color and coefficient (floating point value between 0 and 1)
  93 - \b Diffuse color and coefficient (floating point value between 0 and 1)
  94 - \b Specular color and coefficient (floating point value between 0 and 1)
  95 - \b Emissive color and coefficient (floating point value between 0
  96 and 1). Note: this attribute is applicable only for the OCC viewer;
  97 it simulates light originating from an object.
  98 - \b Shininess
  99 - \b Type of material model: \em physical or \em artificial.
 100
 101 If the material model is specified as a \em physical one (like \em Gold,
 102 for instance), this means that the color of the shape (more precisely
 103 its \em ambient color) can not be modified. If you assign a physical
 104 material model to the shape, the "Color" menu item will not be
 105 available in the popup menu.
 106
 107 If the model is non-physical (\em artificial), the color can be changed
 108 to any appopriate one, only other attributes will be constant. In the
 109 dialog box you will be able to modify the color of the shape via the
 110 "Color" button. "Ambient color" button becomes disabled to signalize
 111 that this attribute of the model is ignored. Also, it will be possible
 112 to modify the color of the shape via the
 113 \ref color_page "corresponding popup menu command".
 114
 115 All available predefined material models are shown in the list box of
 116 the <b>Color and Material Properties</b> dialog:
 117 - <b>[Current]</b> item in the list corresponds to the material model
 118   currently assigned to the selected shape(s). This model can be
 119   freely modified by the user.
 120 - <b>Global</b> material models are shown in blue color in the list;
 121   these are the models predefined by the SALOME Geometry module. The user
 122   is not allowed to modify the global models.
 123 - <b>User</b> materials are shown in black color in the list. These
 124   models are specified by the user and can be modified at any moment.
 125
 126 The buttons "Add material" and "Remove material" in the lower part of
 127 the dialog box can be used to create or remove custom material
 128 models. The same commands are also available via the popup menu that
 129 is shown if the user presses right mouse button in the materials list
 130 box. An additional "Rename material" command, available in popup menu,
 131 can be used to change the name of material model.
 132
 133 <b>Examples:</b>
 134
 135 \image html material_OCC.png
 136 <em>Different materials in OCC viewer</em>
 137
 138 \image html material_VTK.png
 139 <em>Different materials in VTK viewer</em>
 140
 141 The default material model is specified via the preferences of Geometry
 142 module.
 143
 144 */
 145