How To

Description

This page shows how to manage in 3DHOP the visibility and the appearance of the meshes placed on the virtual scene.

Featured Set Scene Elements

  • ModelInstances


Visibility, solid color and transparency

Click to run live demo
Models visibility, color, and transparency in 3DHOP

Set Up Instance Visibility

When composing an interactive 3D scene is certainly useful to be able to manage the visibility of the various geometries on the scene. For example, you may want to visualize a collection of 3D models, but not all of them simultaneously visible on-screen, or you may have a cultural heritage artefacts made of multiple pieces (each one a separate 3D model) and you want to turn on or off the visibility of certain parts of the artefact while exploring it.
3DHOP allows to control the visibility of each instance (or groups of them) in a simple and intuitive way.

First of all, it is possible, when declaring the instances of the scene, to set their start-up visibility status, by specifying the parameter "visible" and assign to it a value: "true" makes the instance visible at startup, while "false" will keep it hidden.
If the "visible" parameter is not explicitly specified, the default value ("true", which means the instance IS visible) will be used.
As shown in the code box here below, the example of this page has five model instances ("Base", "Cage", "Lady", "GargoSingle" and "GargoMulti"), but only three of these are initially visible on the scene ("Base", "Cage" and "GargoSingle").

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    modelInstances: {
      "Base": {
        mesh: "Cube",
        transform: { ... },
        useSolidColor: true,
        color: [0.5, 0.7, 0.7]
      },
      "Cage": {
        mesh: "Cage",
        transform: { ... },
        useTransparency: true,
        alpha: 0.5
      },
      "Lady": {
        mesh: "Laurana",
        transform: { ... },
        tags: ["Group"],
        visible: false
      },
      "GargoSingle": {
        mesh: "GargoyleSingle",
        transform: { ... },
        tags: ["Group"]
      },
      "GargoMulti": {
        mesh: "GargoyleMulti",
        transform: { ... },
        tags: ["Group"],
        visible: false
      }
    },
    ...
  });
}

Beside setting up the visibility status at startup, it is also possible to control the visibility of the instances during the visualization, by calling some ad-hoc JavaScript functions exposed by 3DHOP:

isInstanceVisibilityEnabledByName-returns the visibility status of a specific instance selected by name (the unique ID);
setInstanceVisibilityByName-sets the visibility of a specific instance selected by name (the unique ID);
toggleInstanceVisibilityByName-toggles the visibility of a specific instance selected by name (the unique ID);

The first of the functions above listed ("isInstanceVisibilityEnabledByName(ID)") accepts as input parameter the unique ID name string (enclose in quotes) of the desired instance and returns as output a boolean variable that specifies its visibility status ("true" if the instance is currently visible, "false" if it is not).
The second function ("setInstanceVisibilityByName(ID,newstate,redraw)") set the visibility status of an instance; it takes in input three parameters: the ID name string (enclose in quotes) of the desired instance, a boolean variable that defines the new visibility status ("true" to set the visibility on, "false" to set it off) and another boolean variable that ask for an immediate redrawing of the scene ("true" to redraw, "false" to not redraw).
Finally the "toggleInstanceVisibilityByName(ID,redraw)" function toggles the current visibility status of an instance; it accepts in input two parameters: the ID name string (enclose in quotes) of the desired instance and a boolean variable that ask for an immediate redrawing of the scene ("true" to redraw, "false" to not redraw).

All these three functions are able to work when the visualization is up and running, and each change the visibility status of a single instance… but what if you want to change the visibility of a instance group in a single shot? While it is possible to call the above functions many times in a row, there is a better way: the tags system.
When declaring an instance in the 3DHOP scene, it is possible to (optionally) specify an additional value, called "tags" for each instance.
As also shown in the above code box, the "tags" field is just a series of strings, that are used to tag the instance: the value of the "tags" field may contain one or more keywords as text strings enclosed in square brackets, delimited by quotation marks and separated by a comma. In the following example, there are 4 instances, each one has 2 tags (detailing which "group" each instance belongs to).


    ...
      "instanceA": {
        mesh: "meshA",
        tags: ["group1", "group3"],
      },
      "instanceB": {
        mesh: "meshB",
        tags: ["group1", "group4"],
      },
      "instanceC": {
        mesh: "meshC",
        tags: ["group2", "group4"],
      },
      "instanceD": {
        mesh: "meshD",
        tags: ["group2", "group3"],
      }
    ...

By having tags properly set, it is possible to switch on and off the visibility of a group of geometry simultaneously, by calling a different set of visibility set/toggle functions, which are similar to the previous ones, but that, instead of a unique ID, they get in input a tag, and they work on ALL the instances which have that specific tag, effectively creating "visibility groups". In the example just above, it is clear that if you turn off the visibility of all the instances containing the "group3" tag, you are affecting two instance simultaneously ("instanceA" and "instanceD"). The tags system is extremely versatile, as it enable the creation of any number of groups, nested groups and overlapping groups with ease.

isInstanceVisibilityEnabled-returns the visibility status of all the instances which have the specified tag;
setInstanceVisibility-sets the visibility of all the instances which have the specified tag;
toggleInstanceVisibility-toggles the visibility of all the instances which have the specified tag;

These methods have exactly the same behaviour and parameters of the corresponding "ByName" ones described above, with input and output parameters, save for the first parameter that, instead a unique ID, is now a string specifying the desired tag.
All these six functions can use as input for the ID or tag string the constant value "HOP_ALL" (without quotation marks), that indicate that the function will work on ALL the instances of the scene. Note that, since both the "HOP_ALL" and "tags" systems act on groups of instances, when you use them to get the visibility status of a group containing both visible and not visible instances, then the system will return "true" if at least one of all the checked instances enables visibility. Please, take a look to the documentation section to find out more.

Obviously these methods, just like others used so far, can be used everywhere in the HTML page, so as to create the most appropriate user interface for the specific case: for example connecting them to a toolbar button, or to a link placed in the page, to a timed JavaScript function, or again to any other HTML element you want. In the main example of the page we have used three of the functions previously exposed ("toggleInstanceVisibilityByName", "setInstanceVisibilityByName" and "setInstanceVisibility"), linked to a couple of HTML input elements: radio buttons and checkboxes.
In particular, the checkbox has been defined in this way:

  ...
  <input type="checkbox" ... onclick="presenter.toggleInstanceVisibilityByName('Cage', true);"> Cage </input> 
  ...

So ticking the various checkboxes the system invert the visibility status of the instance identified by the string taken as first input parameter by "toggleInstanceVisibilityByName" (the instance name "Cage" in this code block example) and then redraws the scene (since the second input parameter is setted "true").

The radio buttons behaviour is instead defined in a little different way:

  ...
  <input type="radio" ... onclick="presenter.setInstanceVisibility('Group', false, false); 
                                   presenter.setInstanceVisibilityByName('Lady', true, true);"> Statue </input>
  ...

In this case, selecting one of these buttons, firstly it is called the "setInstanceVisibility" function, that set to "false" (second input parameter) the visibility of all the instances identified by the "Group" tag (first input parameter), that are the "Lady", the "GargoSingle" and the "GargoMulti" instances, and doesn't redraw the scene (because of the third input parameter, set to "false").
Afterwards, it is called the "setInstanceVisibilityByName" function, that toggles the visibility of the single model instance specified by the radiobutton (in this code box, the one called "Lady", identified by name), and redraws the scene (due to the second input parameter set on "true").

Of course the reported example is only a simple use demonstration of declarative fields and methods provided by 3DHOP to act on (single or grouped) instances visibility. Lots of customizations and combinations are possible to achieve the desired degree of 3D scene personalization.


Set Up Instance Transparency

Strictly linked to the visibility issue there is another features somehow concerning the appearance of the instances on the virtual scene: the instances transparency.
It is possible to ask 3DHOP to render an instance using transparency (and specifying its alpha transparency value); this, like for the visibility feature, can be done when declaring the scene (and it will affect the startup transparency of the instances) and during the interactive rendering, by calling the appropriate functions.
The transparency of an instance is controlled, when declaring the instance in the scene, by the fields "useTransparency" and "alpha". Looking at the first code box of this how-to page, can be seen that the value of "useTransparency" is a boolean value that switch on and off the transparency of the instance (this field is optional, and it is "false" by default, when not specified); while "alpha" regulates the level of alpha transparency of the instance, and its value is a single scalar, varying from 0.0, i.e. completely transparent, to 1.0, i.e. solid (this field is also optional, and it is 0.5 by default, when not specified). Obviously, this "alpha" value is ignored if "useTransparency" is set "false".
As it is easily observable also running this how-to demo, in this specific example you have only a model instance ("Cage") with the transparency option set to "true" (with its alpha transparency value set to 0.5).

To change the transparency and alpha of an instance in the 3D scene during interactive rendering, 3DHOP provides a set of functions, here listed:

isInstanceTransparencyEnabledByName-returns the transparency status of a specific instance selected by name (the unique ID);
setInstanceTransparencyByName-sets the transparency of a specific instance selected by name (the unique ID);
toggleInstanceTransparencyByName-toggles the transparency of a specific instance selected by name (the unique ID);

The first of the functions shown above ("isInstanceTransparencyEnabledByName(ID)") accepts as input parameter the unique ID name string (enclose in quotes) of the desired instance and returns as output a boolean variable that specifies its transparency status ("true" if the instance is currently in transparency mode, "false" if it is not).
The second listed function ("setInstanceTransparencyByName(ID, newstate, redraw, alpha)") instead sets the transparency status of a specific instance taking in input four parameters: the ID name string (enclose in quotes) of the desired instance, a boolean variable that defines the new transparency status ("true" to set the transparency on, "false" to set it off), another boolean variable that ask for an immediate redrawing of the scene ("true" to redraw, "false" to not redraw), and finally an optional parameter that sets the level of alpha transparency desired (a scalar, 0.5 by default, varying from 0.0, i.e. completely transparent, to 1.0, i.e. solid). Finally, the last function ("toggleInstanceTransparencyByName(ID, redraw)") is used to toggle the current transparency status of an instance, and accepts as input two parameters: the ID name string (enclose in quotes) of the desired model instance and a boolean variable that ask for an immediate redrawing of the scene ("true" to redraw, "false" to not redraw).

Just as for the visibility functions described above, also these three transparency functions have their correspondent ones capable of acting on groups of instances using the tag system:

isInstanceTransparencyEnabled-returns the transparency status of all the instances which have the specified tag;
setInstanceTransparency-sets the transparency of all the instances which have the specified tag;
toggleInstanceTransparency-toggles the transparency of all the instances which have the specified tag;

Set Up Instance Solid Color

A third and final appearance property of instances is the solid color rendering. By default, if the meshes have per-vertex color, that color is rendered by 3DHOP. It is possible to change this behaviour, and have an instance rendered in a solid color. This, again, may be done at startup, by changing the declaration of the instance, or during the interactive rendering, by calling the appropriate JavaScript function.
The solid color rendering defined in the scene declaration is controlled, like transparency, by two fields that may be specified for any instance: "useSolidColor" and "color". In particular, as visible in the first code box of this how-to page, "useSolidColor" accepts a simple boolean value that switch on and off the solid color rendering of the instance (this field is optional ans is "false" by default when not specified), while "color" (that is used only if "useSolidColor" has been set "true") uses as a value an array of three numbers specifying the RGB color to be used (also this one is an optional parameter, by default [1.0, 1.0, 1.0], i.e. white, when not specified). So, in the example on top of the page, there is only one model instance ("Base") with the solid color option set to "true", and the color RGB array set to [0.5, 0.7, 0.7].

To change in real time the solid color of an instance in the 3D scene 3DHOP provides also a set of functions, here listed:

isInstanceSolidColorEnabledByName-returns the solid color usage status of a specific instance selected by name (the unique ID);
setInstanceSolidColorByName-sets the solid color of a specific instance selected by name (the unique ID);
toggleInstanceSolidColorByName-toggles the solid color of a specific instance selected by name (the unique ID);

The first of the functions above ("isInstanceVisibilityEnabledByName(ID)") accepts as input parameter the unique ID name string (enclose in quotes) of the desired instance and returns as output a boolean variable that specifies its solid color status ("true" if the instance is currently in solid color mode, "false" if it is not).
The second of these methods ("setInstanceSolidColorByName(ID, newstate, redraw, [color])") instead sets the solid color rendering state for a specific instance, taking in input four parameters: the ID name string (enclose in quotes) of the desired instance, a boolean variable that defines the new solid color status ("true" to use solid color rendering, "false" to not use it), another boolean variable that ask for an immediate redrawing of the scene ("true" to redraw, "false" to not redraw), and finally an optional parameter that sets the desired RGB color (three dimensional array, [1.0, 1.0, 1.0] by default). Finally, the last listed function ("toggleInstanceSolidColorByName(ID, redraw)") is used to toggle the current solid color status of an instance, and accepts as input two parameters: the ID name string (enclose in quotes) of the desired model instance and a boolean variable that ask for an immediate redrawing of the scene ("true" to redraw, "false" to not redraw).

Just as for the other methods described above, also these three functions have their correspondent ones capable of acting on group of instances by using the tag system.

isInstanceSolidColorEnabled-returns the solid color usage status of all the instances which have the specified tag;
setInstanceSolidColor-sets the solid color of all the instances which have the specified tag;
toggleInstanceSolidColor-toggles the solid color of all the instances which have the specified tag;

Also all of these functions (both the ones used for the instance transparency than the ones used for the instance solid color) can accept as input ID or tag string the constant value HOP_ALL (without quotation marks), that indicate that the function will work on ALL the instances of the scene. And also for these functions is true that, getting the information about the status of a group of instances, the system will return "true" if at least one of all the checked instances enables transparency/solid color (please, take a look to the documentation section to find out more).

The example in this page are just a very simple and trivial example on how to use these functions. The visibility, transparency and solid color have been implemented such as to provide the maximum flexibility when creation your 3D scene, and when interacting with it.
Obviously these methods, just like others used so far, can be used everywhere in the HTML page, so as to create the most appropriate user interface for the specific case: for example connecting them to a toolbar button, or to a link placed in the page, to a timed JavaScript function, or again to any other HTML element you want.
This tutorial, however, introduces some of the most versatile and useful features of 3DHOP, indispensable to create complex visualization schemes (almost all of the examples in the gallery section are using these methods).

Summarizing, to obtain with 3DHOP visibility and appearance effects, is required just to associate the rights fields to the desired model instance in "modelInstance" or configure the proper real time functions. Once this is done, you had only to embed these function in the HTML code and… you are done!

The complete sources of this example are provided together the 3DHOP code in the download section.

If you want instead to learn more about how to setup advanced camera and lighting parameters in 3DHOP click here and go to the next HOWTO.