HT for Web 3D Manual

Index


Overview

Underlying Engine

HT provides graphic packages ht.graph3d.Graph3dView of 3D technology based on WebGL. As a graphic interface based on OpenGL ES 2.0, WebGL is a underlying graphic API interface, which is difficult for secondary development. Like other HT packages, the Graph3dView package of HT drives graphic display with the unified HT DataModel. It lowers the technological threshold of 3D graphics development through the encapsulation of WebGL technology. If familiar with the HT data model, an average programmer will need only about 1 hour to learn before he can start 3D graphics development.

Model Designer

At the same time, HT provides a powerful 3D graphic model designer based totally on HTML5 technology. Users can set up various visual 3D scenes quickly without coding. The HT 3D development mode breaks traditions and frees most applications from modeling by professional 3D designers proficient in 3ds Max or Maya, or graphic rendering with integrated engines like Unity3d. HT provides a one-stop plan from modeling to rendering, including 2D package display and data integration.

Browser support

WebGL technology has been supported by most of the latest browsers, caniuse.com/webgl website keeps the latest desktop and mobile browsers supportive for WebGL. Use get.webgl.org to detect whether your browser supports WebGL.

Currently, the PC or mobile versions of Chrome, Firefox, Safari and Opera have already been able to support WebGL, for iOS systems users, please update to iOS8 and above, IE browsers need to be IE11 and above to support WebGL, regardless of the type of the browser you choose, we recommend using the latest version.

If you have to use old IE browsers like IE6, IE7, IE8 and others, or because of HT for Web 3D, and the old machine can not be upgraded to IE11, you can consider the installation Google Chrome Frame plug-in, in the page embedded in the following Tag code snippet, the page will be used to render.

<meta http-equiv="X-UA-Compatible" content="chrome=1">

Users of Google Chrome Frame also need to note: Google Chrome Frame does not support opening web pages directly from local file, you have to deploy the page to the Web server release mode. Google Chrome Frame does not support 64-bit browsers: Currently, 64-bit versions of IE are not supported. It's worth pointing out that 32-bit IE is the default on 64-bit Windows 7. * Google Chrome Frame does not support iframe: At this point ChromeFrame only supports the meta tag detection on top level URLs.. You can use the embedded OBJECT element as a solution to overcome the problem that Google Chrome Frame does not support iframe.

<OBJECT ID="ChromeFrame" WIDTH=500 HEIGHT=500 CODEBASE="http://yourdomain/yourproject/"
        CLASSID="CLSID:E0A900DF-9611-4446-86BD-4B1D47E7DB2A">
    <PARAM NAME="src" VALUE="http://yourdomain/yourproject/">
    <embed ID="ChromeFrameplug-in" WIDTH=500 HEIGHT=500 NAME="ChromeFrame"
        SRC="http://yourdomain/yourproject/" TYPE="application/chromeframe">
    </embed>
</OBJECT>

Google Chrome Frame will no longer support or update from January 2014, the current Google Chrome Frame is the 31 version. This version has been able to provide the Canvas function that HT 2D and 3D required, so HT customers can use Google Chrome Frame to solve the old IE problem. Other questions can be found on the Developer Guide and Troubleshooting of Google Chrome Frame.


3D Basics

3D Coordinate System

The 3D coordinate system of HT consists of three axes: x, y and z, the x-axis points to the right, the y-axis to the above, and the z-axis outside the screen in their positive directions. The rotation of HT system follows the Right Hand Spiral Rule.

2D Coordinate Relations

The 3D coordinate system of Graph3dView is related to but different from the 2D coordinate system of GraphView. The x-axis of 2D coordinate system corresponds to the x-axis of 3D coordinate system. The y-axis of 2D coordinate system corresponds to z-axis of 3D coordinate system. The xy plane of the 2D coordinate system equals to the xz plane of the 3D coordinate system. For example, Node#getPosition() returns {x: 100, y: 200}, it means:

For example, Node#getSize() returns {width: 300, height: 400}, it means:

3D Coordinate Function

The y-axis of the 3D coordinate system is a new axis that is not associated with the 2D coordinate system. The getElevation() and setElevation(elevation) functions are added to the ht.Node to control the y-axis position of the 3D coordinate system where the Node's center is located. The getTall() and setTall(tall) functions are added to control the length of the Node on the y axis. In order to avoid the confusion of 2D and 3D coordinate systems and for the convenience to set the size of the 3D data position, HT adds the following new functions to the ht.Node data:

3D Rotation Function

ht.Node in the 2D coordinate system is controlled by the getRotation() and setRotation(rotation) functions, which correspond to the negative rotation values along the y axis in the 3D coordinate system. At the same time, the 3D coordinate system adds new rotation variables two new rotationX and rotationZ along the x-axis and z-axis respectively, as well as the following new functions:

There is another very important parameter rotationMode for rotation. This parameter is set by getRotationMode()|setRotationMode('xzy'). The order of rotation will affect the final effect. This parameter is used to specify the order of rotation. The default value is xzy, and users can change the rotation sequence mode by setting the following six parameters:

3D Abbreviated Function

HT has a lot of shortcuts for commonly used functions, such as getDataModel()|dm(), getSelectionModel()|sm(), etc. There are also a lot of convenient shorthand functions for 3D:

3D Projection

3D Projection is an algorithm mapping points in 3D space to the 2D plane, which is the process of projecting 3D space objects to 2D screen coordinates. Different algorithm will eventually produce different display effects of the screen content. HT supports Perspective Projection and Orthographic Projection, the two most commonly used projection algorithms. Graph3dView components use perspective projection by default, and through Graph3dView#setOrtho(true) it can be switched to orthogonal projection.

Perspective Projection

A perspective projection is a method of drawing or rendering on a 2D paper or canvas, in order to obtain a visual effect close to the real 3D object, which is also referred to as a perspective view. Perspective makes far objects smaller, close objects larger. Parallel lines will appear to be closer to the actual visual effects like intersecting.

As is shown in the picture above, the perspective projection eventually shows only the frustum part View Frustum onto the screen. The Graph3dView provides parameters like eye, center, up, far, near, fovy and aspect to control the specific scope of the frustum body:

near and far can be adjusted according to the actual scene, but it is recommended to let near and far closer to each other within an acceptable range. The closer the better, which helps to avoid the accuracy problem of Z-fighting.

Orthogonal Projection

Orthogonal projection is also called orthogonal view. In this projection mode, objects look the same in size regardless of the distance. The screen image makes people feel different from what they see. Orthogonal projection is useful in modeling, which provides a more "technical" vision of the scene, making it easy to draw and estimate proportions.

Most parameters in orthogonal projection are the same with Perspective Projection, but there is no fovy parameter, which is replaced by the orthoWidth parameter:


3D Model

HT provides a variety of basic types of forms for users in modeling. Different from the traditional 3D modeling methods, HT modeling bases its core on the API interface. It sets through the HT pre-defined meta-type and parameter interface to become able to construct a 3D model. The following sections will describe the predefined 3D model types and setup parameters. Please also refer to the Modeling Manual and the OBJ Manual for more customized extension models.

Hexahedron

Hexahedron is a cube composed of six faces, which is the most commonly used basic beta type in HT system. A hexahedron appears by default when building a ht.Node object. The overall parameters of six faces can be controlled through the all.* in the style. For example, if all.color is set to red, then the default color of all six faces will turn red. If you need to specifically set a certain face, you can control through the left.*|right.*|top.*|bottom.*|front.*|back.* face parameter. For example, set left.color to blue, then the left side will turn red, if left.color is not set, then HT will use all.color value.

By default, mapping will fill the entire picture into the whole face, but in many cases the image needs to be offset from a certain position. Sometimes the tile needs to be tiled in the way Tile, sometimes the map needs to be flipped, and sometimes the layout of the map needs to be dynamically changed to complete special effects like flow and others. In this case you need to customize UV Mapping, tell HT how to attach the picture to the face according to the need of customization through uv parameters:

Shape 3D

The display of 2D graphics of HT in GraphView is determined by the shape attribute of style. Similarly, HT provides the shape3d attribute for 3D, which pre-defines a variety of 3D objects. The default value for shape3d is undefined, and the beta is shown as a hexahedral graphic as described in the previous section. When shape3d is set a certain value, it is displayed as specified by shape3d. The remaining specific parameters are set by shape3d.*:

3d text

HT can render 3D text by loading the corresponding typeface font and specifying the shape3d type of the node as text. Rendering 3D fonts needs a json format typeface font first, for more details please use the website facetype.js to generate, download the generated font (json format), and load fonts into memory through ht.Default.loadFontFace.

Specific control parameters for texts include:

ht.Edge

ht.Edge in the GraphView topology components, as a connection linking nodes, is an important beta type. The display function of 2D connection still exists in the Graph3dView package. It can also realize the 3D connection effect. At the same time, it also added some connection parameters for 3D. Connection in the 3D space is displayed in a non-stereo way by default. By setting style to cylinder, it can be presented as a tubular with 3D effect. The commonly used parameters to build the connection are the followings:

When the edge.type is the type of points, the inflection point parameter set to edge.points is compatible with the JSON format of the 2D {x: 100, y: 100}. The new parameter e is introduced on the 3D to represent the elevation of elevation, so the 3D supports the inflection point parameter in the format of {x: 10, y: 20, e: 30}, which represents the position of the x axis 10, the y axis 30, and the z axis 20.

By setting style to cylinder, it can be presented as a tubular with 3D effect. Then all the parameters to control the connection are inshape3d.*. repeat.uv.length parameter is added with the default parameter being empty. If the length value is set, the texture will automatically adjusts the map multiple in the direction of the connection based on the length of the connection.

Refer to Shape Manual

ht.Shape

Refer to Shape Manual.

Other Parameters

Whole

Label

Text attributes of label.* in 2D still apply in 3D which also support the second internal label2.*, meanwhile it added some attribute parameters in accordance with the layout of 3D space and the features of displaying as following:

Refer to Position Guide

Notes

The attribute of annotation of note.* in 2D also apply in 3D which also support the second internal note.* annotation, meanwhile it added some attribute parameters in accordance with the layout of 3D space and the features of displaying as following:

See examples in Position Guide

Icons

icons is a very useful attribute of HT data extension, and it can be used to add as many icon accessories for data as you want. The sample codes of icons content structure are as following:

data.setStyle('icons', {
   whateverName1: {
       position: 17,
       direction: 'north', // east, west, south, north
       gap: 1,
       names: ['icon1', 'icon2', 'icon3']
   },
   whateverName2: {
       position: 20,
       width: 16,
       height: 16,
       name: ['icon5']
   },
   whateverName3: ...
]);

icons can be divided into many groups, and whateverName* can be understood as the name of a group. This name is not displayed by HT and not used to present interface results. Users can name and manage it according to their demands. Setting the icons objects directly will remove the side effects caused by the icons that have been set. For this reason, HT provides the function of Data#addStyleIcon(name, json) and Data#removeStyleIcon(name) so as to control and manage additions and deletions of icons, therefore the above code can be implemented by the code shown below:

data.addStyleIcon('whateverName1', {
       position: 17,
       direction: 'north', // east, west, south, north
       gap: 1,
       names: ['icon1', 'icon2', 'icon3']
});
data.addStyleIcon('whateverName2', {
       position: 20,
       width: 16,
       height: 16,
       name: ['icon5']
});

From the sample code above, you can find that every group of icons defines icon5 for single icon as well as puts many icons in order, such as ['icon1', 'icon2', 'icon3'] of whateverName1. Other parameters of json are related to how to set and display these icons. The other parameters of json are associated with how to place and display these icons.

Attach

The function of attaching is very convenient for designing hierarchically related mode, for example, device panels attach rack and device ports attach device panels. So it will shape the mode of frame-panel-port attaching, and when users drag the whole frames, all graphical elements of this hierarchy will move accordingly. In the context of 3D, the concept of host extends further. When rack shift anywhere in 3D space and rotate by arbitrary angle, all related host graphical elements would pan correctly. They will do some rotation to corresponding location. As a result, all parts of images of the whole device will relatively uniform in location of scenes.

3D components

Component Basis

Displaying 3D view of HT component are ht.graph3d.Graph3dView, ht.graph3d is a package related to 3D components, Graph3dView is a kind of components for presenting 3D view. By analogy with ht.graph.GraphView as 2D view components, both GraphView and Graph3dView can share the same data model DataModel. The design of API in 2D and 3D, HT kept consistency in many places.

The DOM structure, the interface of Graph3dView, consists of the bottom element div and renders layer element canvas. The div can be gotten by getView() while the canvas can be gotten by getCanvas(). The interactive events of HT default are added on the bottom element div, so users can make custom interaction extension through adding ways of events listener on elements returned by getView().

Color parameters are flexible in HTML. They can be the hexadecimal format of #F0F1F2, string names such as red and black, the format of rgb(255,128,32) or the format rgba(255,128,32,0.5) that contains transparency. However, in matter of the API interfaces of WebGL, it is generally required that values of four rgba parameters vary from 0 to 1 (0~1). So default values of color parameters for Graph3dView components are formatted in numbers array of [r,g,b,a], but considering compatibility of Data and 2D on DataModel, color parameters will be transformed automatically inside HT. Therefore, no matter data.s('all.color','red') or data.s('all.color',[1,0,0,1]), they all have the same effects.

Light Setting

Lighting, frog and other effects refer to Lighting Guide

Grid Axis

In order to provide 3D space coordinate reference, Graph3dView has prepared real xz surface grid, three direction axes of x,y and z, and the displaying function of central point position. All these parameters close the status of not displaying, and you can open the switch and change the displaying parameters of as required.

3D Interaction

Interaction Basis

Default Mode

There is a big difference of interaction between 3D and 2D. It is set default that Graph3dView provides the rotation along central point of Graph3dView#getCenter(). When you operate Drag in this mode, it will change the location of eye observation points for Graph3dView#getEye(), mouse wheel and zooming effects of touch screen pinch. Actually, it will change the position of eye as well, which make the eye close to the central position of center or further away from it. Eventually, the effects of approaching and moving away from something and zooming effects will be achieved.

First Person Mode

Graph3dView also provide the interactive roaming model of first person; this mode will change the position of eye and center at the same time. You can switch to First person mode by Graph3dView#setFirstPersonMode(true), and this mode will produce the results that passengers are walking and cars are travelling:

The parameters of Graph3dView#setMouseRoamable(true|false) can be set in the mode of first person. The default value is true. When you set the false, the mouse will lose the function of moving forward and backward; in this condition, the left mouse button can drag and edit graphic elements and the right mouse button can change the view directions; the above operation will combine with roam operation by using w|s|a|d buttons on keyboard.

Interaction Function

Interaction functions of HT generally contain parameter anim that means whether to start animations. This parameter can be simply true|false type of boolean, and can be the json object as well. When the parameter is the json object, it means starting the animation. Meanwhile the attributes of the json object will be applied to control parameters related to animation. You can refer to the sample code snippets as following:

g3d.walk(distance, {
    frames: 50,
    interval: 30,
    easing: function (t) {return t; },
    finishFunc: function () {
        forwardIndex += 1;
        if (points.length - 2 > forwardIndex) {
            g3d.setCenter([point2.x, 1600, point2.y]);
            setTimeout(function () {
                g3d.rotate(Math.PI / 2, 0, {
                    frames: 30,
                    interval: 30,
                    easing: function (t) {return t;},
                    finishFunc:function () {forward();}
                });
            }, 60);
        } else {
            var lastPoint = points[points.length  - 1];
            g3d.setCenter([lastPoint.x, 1400, lastPoint.y]);
            setTimeout(function () {
                g3d.rotate(-Math.PI / 2, 0, {
                    frames: 30,
                    interval: 30,
                    finishFunc: function () {
                        window.isAnimationRunning = false;
                    }
                });

            }, 60);
        }
    }
});

Although the nature of 3D interaction is to change the position parameters of eye and center, direct operation of 3D coordinate points is too raw and obscure. Graph3dView gives clearer and more intuitive way for function operating below:

Interactive switch

By default, the following parameters are in open status; you can use the mouse or keyboard to perform the following interoperability, according to the requirements of the switch settings:

Keyboard operation

Graph3dView Preset a lot of keyboard operation

Graph3dView by default, the moving data move along the xz plane and change the moving mode when the following keys are pressed:

If you want to change the default implementation in move mode by keyboard, you can apply the function of getMoveMode(event, data). The default implementation of the function is as following: If the style attribute 3d.move.mode specified in the final element specifies the value, the keyboard state is no longer taken into account and the setting value is used:

getMoveMode: function (event, data){
    var movemode = data.s('3d.move.mode');
    if(movemode){
        return movemode;
    }
    var map = ht.Default.getCurrentKeyCodeMap(),
        x = '88',
        y = '89',
        z = '90';
    if(event.shiftKey || (map[x] && map[y] && map[z])) return 'xyz';
    if(map[x] && map[y]) return 'xy';
    if(map[x] && map[z]) return 'xz';
    if(map[y] && map[z]) return 'yz';
    if(map[x]) return 'x';
    if(map[y]) return 'y';
    if(map[z]) return 'z';
    return 'xz';
},

See it in Adsorption chapter example, and set the code of the move mode to move along the xyz in 3D space:

g3d.getMoveMode = function (event){
    return 'xyz';
};

Data Edit

By default, the data can be dragged along the xz plane in a 3D scene, or Combine keyboard achieves any movements to any directions in space, but after all this method is not direct and easy to use. At the same time the data have rotation angle of three axes, the size of the three axis size and other parameters need to control, that is, need to modify the editing function of p3, s3 and r3 parameters. For this reason, HT provides an intuitive solution that, when `Graph3dView#setEditable (true) is in edit state, the last selected data will present the following: The center of data extends control bar of three axes, and the control bar of each axis has been divided into three parts.

See filter section to know whether the data are allowed to move, rotate and scale.

Interactive monitoring

You can monitor the process of interaction by Graph3dView#addinteractorListener:

g3d.addinteractorListener(function (e){
    console.log(e.kind);
});

The parameters type of callback events e.kind are as following:

When you click or double-click on the data, in addition to the return event such as e.kind, the e.part parameter also provides information about which part of the data should be clicked.

Collision Detection

HT not only provide first person roaming interactive mode, but also supports the detection the collision with any blocks like wall in the roaming process. This collision detection can limit the allowed scope of first person roaming. Roaming generally operates along the xz plane, so HT provides the multi-lines to define the xz plane in order to describe the roaming boundary that can not go beyond. The boundary of collision can be specified by Graph3dView#setBoundaries(boundaries), the format of boundaries are following:

g3d.setBoundaries([
    [
        p0.x, p0.y,
        p1.x, p1.y,
        p2.x, p2.y,
        p3.x, p3.y
    ],
    [
        p4.x, p4.y,
        p5.x, p5.y,
        p6.x, p6.y
    ]
]);

The above code sets two polylines p0-p1-p2-p3 and p4-p5-p6, array describe all endpoints in each polyline, and the first and second element means the x, z coordinates of start point. The following are the x, z coordinates of the second, third and other endpoints; you can understand that the MoveTo goes to the first endpoint and then LineTo the shape of other endpoints. The following sample code apply the function of ht.Default.toBoundaries(data.getPoints(), data.getSegments()). This function can convert discontinuous curves into differential straight lines segments. The code uses GraphView#addTopPainter, the position orientation information of eye and center in 3D are real-time rendered in 2D so as to intuitively understand the position and orientation of the current first person.

Selected State

The data in Graph3dView selected are displayed in a darker status, and the dark coefficient is determined by the attributes of brightness, select.brightness and the style. The default attribute value of select.brightness default value is 0.7, the final return value is more than 1 with brighter result, less than 1 with darker result, equal to 1 without any changes or null result. Graph3dView#getBrightness function controls the final brightness of data, so you can also override the brightness of data that is selected by this function in user-defined manners, the following is the default logic:

getBrightness: function (data){
    var brightness = data.s('brightness'),
        selectBrightness = this.isSelected(data) ? data.s('select.brightness') : null;

    if(brightness == null){
        return selectBrightness;
    }
    if(selectBrightness == null){
        return brightness;
    }
    return brightness * selectBrightness;
},

Graph3dView#getWireframe function is used to define the result of 3D wire frame for data; the default implementation code is as follows. Through the code, we can know that the result of displaying the selected wire frame by controlling the related wf.*wf is the abbreviation of wireframe).

getWireframe: function (data){
    var visible = data.s('wf.visible');
    if(visible === true || (visible === 'selected' && this.isSelected(data))){
        return {
            color: data.s('wf.color'),
            width: data.s('wf.width'),
            short: data.s('wf.short'),
            mat: data.s('wf.mat')
        };
    }
},

Filter

Select the filter

By default, all data can be selected and users cancel the function of being selected of some data by setting the selection of filters, The final control that decides whether to be selected is in the filterFunc filter on SelectionModel model by reloading the isSelectable function of the GraphView, or calling the packaged function control of GraphView.setSelectableFunc(func). The sample code is as follows:

graph3dView.setSelectableFunc(function (data){
    return data.a('selectable');
});

Visible filter

In default situation, data are visible, and users can set the visible filters to hide part of data, the sample code is as follows:

graph3dView.setVisibleFunc(function (data){
    return data.s('all.transparent') === true;
});

The example code logic is to only display the data which all.transparent is true. The Graph3dView#isVisible function ultimately determines whether the metafile is visible, so you can also override the function:

graph3dView.isVisible = function (data){
    return data.s('all.transparent') === true;
};

Movable filter

By default, all data can move, users can fix part of data by setting movable filter, and the sample code is as follows:

graph3dView.setMovableFunc(function (data){
    return movableItem.selected;
});

The sample code logic is when the selected of movableItem's selected is true, the data can move. Graph3dView#isMovable function ultimately determines whether the data can moved, so you can also override the function:

graph3dView.isMovable = function (data){
    return movableItem.selected;
};

Rotatable filter

When Graph3dView#setEditable(true) is set to be editable, the selected data can rotate by default. The following code can be used to prohibit part of data to rotate:

graph3dView.setRotationEditableFunc(function (data){
    return data instanceof ht.Shape;
});

The logic of the above code is that only data of the ht.Shape type are allowed to rotate. Graph3dView#isRotationEditable function ultimately determines whether the data can be rotated, so you can also override the function:

graph3dView.isRotationEditable: function (data){
    return data instanceof ht.Shape;
},

Scalable filter

When Graph3dView#setEditable(true) is set to be editable, the selected data can rotate by default. The following code can be used to prohibit part of data to rotate:

graph3dView.setSizeEditableFunc(function (data){
    return data instanceof ht.Shape;
});

The logic of the above code is that only data of the ht.Shape type are allowed to change the size. Graph3dView#isSizeEditable function ultimately determines whether the entity can be resized, so you can also override the function:

graph3dView.isSizeEditable: function (data){
    return data instanceof ht.Shape;
},

In addition to setting the filter on the view components, the internal filtering mechanism for GraphView and Graph3dView also refers to the following style attributes, users can directly change the following style to achieve the result of controlling single data:

Debug information

Export

Export some snippets of examples:

{
    label: 'Export Image',
    action: function (){
        var w = window.open();
        w.document.open();
        w.document.write("<img src='" + g3d.toDataURL(g3d.getView().style.background) + "'/>");
        w.document.close();
    }
}

Welcome to contact us service@hightopo.com