Quick-start with OpenGL/WebGL

Introduction

In this overview we will give additional information about the default rendering for WebGL and OpenGL using the wizard built into the paramate cloud Admin. We will explain the underlying concept of the default rendering, what materials are available and how to use them in your configurator. A glimpse into individual adaptions of the rendering and some basic information about camera and viewport settings come at the end.

The necessary files for defining the rendering for your paramate configurator can be auto-generated by clicking on the wizard icon in the rendering section. (You might already know that after reading our Getting Started tutorial and/or our Creating Configurators Walkthrough tutorial.)

If you do not want more information on how technically the default rendering works but just quickly want to learn what materials are available and how to use them in your configurator, you can jump down to the section about materials available for default OpenGL/WebGL rendering.

How does the default rendering with OpenGL/WebGL work in paramate?

The default rendering is a matcap rendering. "matcap" stands for "material capture". The idea is to have all information about lighting, reflections, and material roughness captured in simple texture images without the need to specify or control any lighting in addition.

In the simplest case you can think about the matcap texture image as a sample rendering picture you would get when rendering a perfect sphere. So, if you use the picture of a golden sphere with lighting from the left as a matcap texture, then your rendered object would look like made from the same gold material with lighting coming from the same direction as in your picture. If you change the picture to show a matt plastic ball with lighting from above, the rendering will change accordingly. This makes it quite easy to modify material appearance by just changing the images used as matcap textures with 2D graphics programs. Here are some examples for matcap texture images and the resulting rendering:

But how is it working? The trick is normal mapping. Since the picture is showing a sphere, each position on the 2D image corresponds to one normal vector relative to the viewing direction of the camera. For example, the center position of the image corresponds to vertical inclination. This way, the matcap texture is a normal map for the renderer. For each normal vector the renderer can look up in the matcap texture image what color value belongs to that inclination.

As can be seen from the example above, in the simplest case the whole coloring of an object can already be fully defined and fixed in the matcap texture. But that would be quite inconvenient in some cases, e.g for dynamic coloring. That is why in our default rendering files we provide more advanced rendering using matcap textures that makes it possible to change the base color of an object dynamically while keeping the glossy highlights unaffected by that, transparency is possible as well.

After knowing the concept of the matcap rendering, let’s have a look at the files generated by the wizard. Two folders and one file are generated.

The first folder is the img folder, holding the matcap texture images. You can download the images and have a look. They are indeed images showing spheres.

The second folder is the shd folder, holding the OpenGL /WebGL shader files. The shader files tell the renderer what to do, in this case defining the procedure for a matcap rendering. Those files hold all the math and calculations the renderer needs. It includes procedures for applying external coloring, transparency and specular lighting by combining more than one matcap texture image in one rendering.

The last item is a single file, called scene.json. This is a JSON file holding information for paramate how to use the shaders, especially what shaders are to be used for which material that belongs to a certain material id. Information about default camera setting can, but do not have to be included as well in this file.

What materials are available for default OpenGL/WebGL rendering in paramate?

In paramate each render material is addressed with a material id, an integer number normally starting from 0. These ids are used in your configurator's CAD file to define the rendering material for each model part.

For the default rendering with OpenGL/WebGL different materials are predefined. For some materials a color can be set individually per part at runtime and for some the color is fixed.

The available materials and their ids are listed below:

  1. Matt (like matt plastic), color can be set
  2. Glossy (like glossy plastic or ceramics), color can be set
  3. Metal (like color-coated shiny metal), color can be set
  4. Grey metal (like shiny silver or steel), color fixed
  5. Gold (like shiny gold), color fixed
  6. Copper (like shiny copper), color fixed
  7. Semi-transparent matt (like matt transparent silicone), color can be set
  8. Semi-transparent glossy (like semi-transparent glass), color can be set
These default rendering materials give nice results for many applications. Advanced effects like shadows, reflections and refractions are not available, though.

How to use the rendering material in your configurator in paramate?

For connecting the rendering material with the material defined in the configurator’s CAD files(s), the material id is used. How to "apply" a material with a specific id to a model depends on the CAD system used. For trCAD, paramate’s native CAD system, find more information on the Materials Documentation of trCAD.

Information for other systems can be found on our List of Supported CAD Systems.

How to define or change the OpenGL/WebGL rendering materials in paramate?

The materials available for rendering, their id and which rendering files paramate should use for the materials are defined in the JSON file scene.json in the "materials" object. When editing the scene.json please keep with the general JSON object structure you can find in the scene.json file for the default rendering to avoid errors.

If you are quite new to WebGL rendering or just want stay with the default rendering and only adapt some things like position or intensity of the lighting, then the easiest is to mainly change the matcap texture images and leave the rest unchanged. If you want to have glossy materials with colors changed on runtime, notice that in this case you need two matcap images, one for the matt, diffusive part, where color is applied to on runtime and one for the specular lighting only, independent of coloring and ideally holding no additional information. Have a look at the default matcap images for the glossy material with id 1 for inspiration.

When using your own matcap texture images, keep in mind that those images are used as a normal map. See section "How does the default rendering with OpenGL/WebGL work in paramate?" above for more details. This fact implies some limitations for images used as matcap textures. They have to be positioned perfectly centered and be cropped in a way, that the sphere does exactly fill a quadratic image, no surrounding boundaries allowed. If the image shows a sphere with visible surface structure like bumps or marmorated coloring, this will not give the expected result, because the renderer will translate those surface structure into normal mapping. Another technical limitation is, that the size of the quadratic image can only be a power-of-two (128 x 128, 256 x 256, 512 x 512, etc.).

If you are familiar with shader programming for OpenGL/WebGL you can generate your own custom rendering materials. A good starting point is to have a look inside the default rendering files and adapt those to your needs. One thing to note is that for OpenGL paramate currently only supports the OpenGL ES subset, so that the same shaders can be used for WebGL as well. In addition, until now paramate does not support post-processing in general, a special setting is implemented for anti-aliasing, though. If you want to know more about rendering options, please contact us.

How to control camera and viewport?

There are more settings for visualization beyond the renderer. Viewport and camera can be set using paramate’s JavaScript API. Please refer to the JavaScript API manual to learn more. As a dive-in we recommend the "Launching a Configurator" walkthrough for the JavaScript API.

Specific settings for viewport and camera can be found in the section "Viewport and Camera" of the JavaScript API documentation.

If you want to change the default initial setting for the camera, those can be set in the file scene.json as well in the optional "camera" object. This object holds six key-value pairs for setting the initial camera position, for example for the view direction and the camera aperture. As an example, the "camera" object section of the scene.json file could look like this:

"camera": 
  { 
    "aperture": 25,
    "origin"  :[ 0, -12.5, 0 ],
    "focus"   :[ -527.2088359520229, -161.80936519185383, -20.754015318836877 ],
    "view"    :[ 0.9614691202392133, 0.2722950265718821, 0.03784903341765906 ],
    "top"     :[ 0.06271956017074834, -0.35130950584479536, 0.9341562438238443 ],
    "right"   :[ 0.26766282446096423, -0.8957885071864361, -0.3548514658195388 ]
  }

It is in most cases not recommended to choose the vectors by hand, as they have to match to each other. Instead use a test configurator, adapt the camera via the user interface as desired and then extract the values and copy-paste them into the scene.json file. Read the tutorial "How to set up camera movements" to learn how to extract the values of the camera parameters from a test configurator. More information about the camera movement and the meaning of the camera parameters can be found in the section "Viewport and Camera" of the JavaScript API documentation.