TWaver MONO Design
1. 概述
TWaver MONO Design 基于WebGL技术来完成3D场景的渲染,因此构建3D场景及场景内对象是渲染的基础。众多的3D实体对象(例如机柜,交换机,桌,椅)以及场景环境(例如灯光,镜头等)共同实现整体场景的实时渲染。为了能够便捷地描述和构建3D实体对象,MONO Design定义了基本的模型对象结构和数据描述格式,方便用户周详地组织数据和模型转换。
Mono内对于模型对象进行了分类管理,定义了基本的数据模型对象,称为原型对象(Primitive)。原型对象提供了基本的模型形状,例如Cube,Cylinder,每个原型对象需要基本的3D属性描述,比如大小(size)、位置(position)、旋转角度(rotation)等。原型对象还提供了材质支持,增强模型对象的逼真渲染,常见的例如纯色支持,贴图支持等。原型对象可以用来描述单个的业务对象,例如使用Cube对象(设定交换机的贴图)描述一个交换机,使用Cylinder对象(配上石材贴图)描述房间的一个柱子。构建一个常用的机房内使用场景时,完全可以仅仅通过这些基本对象配置贴图,设置大小、位置、旋转角度等空间信息,来表示墙体、窗户、门、机架、交换机、空调、UPS、服务器等,这个过程称为建模。
原型对象可以相互组合成具有整体意义的模型对象,称为拼装(Assembled Models)。拼装可以详细地描述一个业务对象的详细结构,并且满足后续应用时减少编辑,以整体的概念使用一组对象的需求。拼装的组成部分可以是一组的原型对象,还可以包含其他的拼装对象。
房间由基本的墙体(外墙和内墙),门、窗、地板构成。通过定义墙体的顶点勾勒房间形状,并可设置墙体的高度和厚度。窗和门的位置可以通过空间坐标来定义,也可以固定在指定的墙体上。最后,将拼装对象和房间统一输出到图纸,即可构建出3D场景。
本文档针对原型对象、拼装对象、图纸输入的数据格式进行重点介绍。
2. 原型对象
原型对象通过对基本形状的定义,来展现简单的业务对象。原型对象的属性可分为必需属性,可选属性以及扩展属性。必需属性主要定义了原型对象在3D空间内的基本形态,可选属性主要是对原型对象材质、贴图的描述。其他可选属性,将陆续在扩展属性中添加。
以下是一个原型对象的JSON描述:
{ "size": {"x": 100, "y": 150, "z": 80}, "className": "mono.Cube", "rot": {"x": 0, "y": 0, "z": 0}, "ambient": [{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 },{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 } ], "color": [{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 },{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 }], "id": "E427D7FC289874506919A0852BF9506DA", "scale": { "x": 1,"y": 1, "z": 1}, "dt": ["images/chassis01.png", "images/chassis05.png", "images/metal09.png", "images/metal09.png", "images/metal09.png", "images/metal09.png"], "groupid": null, "transparent": [false, false, false, false, false, false], "types": ["phong", "phong", "phong", "phong", "phong", "phong"], "visible": [true, true, true, true, true, true], "opacity": [1, 1, 1, 1, 1, 1], "repeat": [[3, 3],[3, 3],[3, 3],[3, 3],[3, 3],[3, 3]], "type": "primitive", "shape": "PrimitiveModel" }
2.1 必需属性
原型对象的必需属性包括原型对象的形状、尺寸、旋转角度、编号、缩放比例等。
2.1.1 className
className用于描述原型对象的形状,必须为mono.Cube,mono.Cylinder,mono.Sphere,mono.Torus,mono.Billboard等。原型对象可以用来描述单个的业务对象,例如使用Cube来描述一个交换机,使用Cylinder对象来描述一个柱子,使用Sphere对象来描述一个地球的形状等。定义完原型对象的形状后,可以用大小、位置等描述其在3D空间内的形态,以及材质等外观。
示例:
"className":"mono.Cube", "className":"mono.Cylinder", "className":"mono.Sphere", "className":"mono.Torus", "className":"mono.Billboard",
2.1.2 size
size用于描述原型对象的尺寸,通常以三个数值表示,例如一个立方体cube的尺寸用”长,宽,高”来确定,一个圆锥cylinder的尺寸用”上表面直径,高度,下表面直径”来确定。当圆锥的上表面直径=下表面直径时,则为圆柱。一个球体的尺寸用其在x,y,z三个轴向上的直径来确定,等等。
Cube: 长,宽,高
Cylinder: 上表面直径,高度,下表面直径
Sphere: 直径,直径,直径
Billboard: 宽度,高度,z保留
示例:
"className":"mono.Cube", "size": {"x": 80, "y": 80, "z": 80},
表示长、宽、高各为80的一个立方体。
2.1.3 rot
rot用于描述原型对象相对于本地坐标系的旋转角度(单位为角度,例如30˚),通过定义其绕x轴,绕y轴,绕z轴的旋转角度,来描述原型对象在空间内的位置形态。其中,环轴逆时针为正向,x,y,z的数值为实数,0表示没有旋转。
示例:
"rot":{"x": 90, "y": 0, "z": 0}
表示原型对象在x轴逆向旋转90度。
2.1.4 id
id用作导入原型库时的检索ID,可以任意定义,需为唯一编号。在拼装对象构架的时候,使用这个id来做内部子节点编号。
示例:
"id":"EF59CEF30F84544ECABA086DF21047EE4",
2.1.5 scale
scale用于描述原型对象相对于本地坐标系,在x、y、z轴向上的缩放比例,1表示100%无缩放,2表示缩放为200%,以此类推。
示例:
"scale": { "x": 1,"y": 1, "z": 1},
2.2 可选属性
原型对象的可选属性主要用于对象材质的表现,包括对象的材质类型、颜色、是否可见、透明度、贴图路径、贴图覆盖方式等。
2.2.1 types
types用于描述原型对象表面所覆盖的材质类型。材质类型的可选值为”basic”和”phong”,默认值为basic。如果type的属性为一个字符串,则表示用该值对应的材质来覆盖整个模型。如果type的属性为数组,则可用于描述模型不同面区的材质类型。数组的长度由对象的面区数量决定,例如,Cube六面材质类型,需要6个数值来描述其(left,right,top,bottom,front,back)六个面的材质;Cylinder三面材质类型,需要3个数值来描述其(side,top,bottom)三个面的材质。
示例:
"types":["basic","basic","basic","basic","basic","basic"]
表示Cube六面采用basic材质。
2.2.2 color
color用于描述对象各个面上晕染的颜色。颜色值使用rgb颜色代码表示,如默认值{“r”: 1, “g”: 1, “b”: 1}。如果color的属性类型为一组rgb的对象表示时,表示整体全部用该颜色晕染。如果color属性类型为一个数组,则表示不同面区域材质上晕染的颜色。数组的长度可随模型形状的面区数变化,例如,Cube六面材质类型,需要6个数值来描述其(left,right,top,bottom,front,back)六个面的颜色;Cylinder三面材质类型,需要3个数值来描述其(side,top,bottom)三个面的颜色。
示例:
"color": [{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 },{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 }]
表示Cube六面都晕染{"r": 1, "g": 1, "b": 1}颜色。
2.2.3 visible
visible用于描述对象各个面上的材质是否可见。默认值为true,表示整体全部可见。
该属性类型为一个boolean时,表示整体全部可见。该属性类型为一个数组时,表示不同面区域材质是否可见。数组的长度可随模型形状的面区数变化。
例如,Cube六面材质类型,需要6个数值来描述其(left,right,top,bottom,front,back)六个面是否可见;Cylinder三面材质类型,需要3个数值来描述其(side,top,bottom)三个面是否可见。
示例:
"visible":[true,true,true,true,true,true]
表示Cube六面材质可见。
2.2.4 opacity
opacity用于描述对象各个面上材质的透明度,默认值为1,表示不透明,取值范围0-1。
该属性类型为一个float时,表示整体材质的透明度。该属性类型为一个数组时,表示不同面区域材质的透明度。数组的长度可随模型形状的面区数变化。
例如,Cube六面材质类型,需要6个数值来描述其(left,right,top,bottom,front,back)六个面的透明度;Cylinder三面材质类型,需要3个数值来描述其(side,top,bottom)三个面的透明度。
示例:
"opacity":[1,1,1,1,1,0.5]
2.2.5 imageType
除了原型对象本身的材质属性外,可对原型对象进行贴图,来展现其颜色、材料等外观。
imageType用于描述在原型对象上的贴图覆盖方式,需要贴图时必需有该属性赋值。imageType的属性值按原型对象形状的面区数量有所不同:
1表示覆盖贴图方式
6表示在Cube对象上六面贴图的方式
3表示在Cylinder对象上三面贴图的方式
示例:
"imageType":6
表示在对立方体进行六面贴图,每个面的贴图都可以分别用不同的贴图路径。
2.2.6 dt
dt用于描述原型对象贴图的路径,可以是相对路径,也可以是绝对路径。该属性与className类型相对照,材质中需要贴图时必需有该属性赋值。
如果是一个字符串,表示用此贴图来覆盖整个模型,或者作为billboard对象的用图。
如果是数组类型,表示不同面区域的贴图。数组的长度随着模型形状的不同而有不同。
长度为6:Cube六面贴图路径,六个面依次为left,right,top,bottom,front,back
长度为3:Cylinder三面贴图路径,三个面依次为side,top,bottom
示例:
"dt":[ "images/chassis01.png", "images/chassis05.png", "images/metal09.png", "images/metal09.png", "images/metal09.png", "images/metal09.png"]
2.2.7 transparent
transparent用于描述原型对象是否支持贴图透明度,默认值为false,不支持。如果该值为true,则会对贴图的透明度进行处理。如果为false,则无论贴图是否有透明或半透明属性,都不进行处理。该属性与className类型相对照。如果是一个boolean,表示支持覆盖整个模型的贴图有透明度;如果是数组类型,表示支持不同面区域的贴图的透明度。数组的长度随着模型形状变化。
长度为6:Cube六面贴图的透明度属性,六个面依次为:left,right,top,bottom,front,back
长度为3:Cylinder三面贴图的透明度属性,三个面依次为:side,top,bottom
示例:
"transparent":[false,false,true,true,false,false]
2.2.8 repeat
repeat用于描述对象贴图时是否采用平铺的方式,默认为false不平铺。该平铺属于重复的,永远均匀的平铺。
该属性类型用数组来描述其平铺方式。如果数组内元素是数字,数组长度应该为2,表示支持用来所有面贴图平铺规则。例如repeat:[2,2],表示所有面上的贴图都是平铺,根据uv坐标系,分别是2幅,2幅平铺。
如果是数组内元素还是一维数组,表示不同面区域贴图的平铺规则。
数组的长度随着模型形状的不同而有不同。
示例:
"repeat": [[3, 3],[3, 3],[3, 3],[3, 3],[3, 3],[3, 3]]
2.3 扩展属性
2.3.1 radialSegments:Cylinder
侧面的分片数。数值越高,侧面越平滑。
取值范围>=3,默认值为4。
示例:
"radialSegments":5,
3. 拼装对象
几个原型对象进行拼装后,可以用于表现更加复杂的业务对象,我们称之为拼装对象。拼装时,需指定其中的一个对象为主对象,以该主对象中心为相对原点,来描述其他对象相对于该原点的位置、旋转角度以及相对于自身的缩放比例等。
下图为使用两个cylinder对象和一个cube对象组成的拼装对象。
以下是一个拼装对象的数据格式:
"children":[ { "id":"p01", "OID": "main", "ishost": true }, { "id":"p02", "pos": {"x": 52, "y": 62,"z": 19} "rot": {"x": 0, "y": 0, "z": 0}, "scale": { "x": 1,"y": 1, "z": 1}, }, { "id":"p03", "pos":["x": -148.71,"y":-18.58,"z":0], "rot": {"x": 0, "y": 0, "z": 0}, "scale": { "x": 1,"y": 1, "z": 1}, }, { "id":"assemble-01", "pos:["x":-10,"y":-18.58,"z":0] } ] }
3.1 id
拼装对象的id编号,拼装对象内的所有id必需为唯一,不能重复。
3.2 OID
"OID": "main"用于描述拼装对象内的主对象。其他拼装对象以主对象的中心为相对原点,来定义位置、缩放比例等。
示例:
"id":"p01", "OID": "main", "ishost": true
3.3 pos
pos用于描述拼装对象的中心以主对象的中心为相对原点,在x,y,z轴向上的坐标。
示例:
"id":"p02", "pos":["x":10,"y":20,"z":0]
3.4 rot
rot用于描述拼装对象的中心以主对象的中心为相对原点,绕x,y,z轴的旋转角度。其中,环轴逆时针为正向,x,y,z的数值为实数,0表示没有旋转。
示例:
"id":"p03", "rot":["x":0,"y":90,"z":0]
3.5 scale
scale用于描述拼装对象相对于自身在x,y,z轴向上的缩放比例。1表示100%无缩放,2表示缩放为200%,以此类推。
示例:
"id":"p03", "scale":["x":1,"y":2,"z":0.5]
4 图纸
原型对象构建的简单业务对象,或者拼装对象构建的复杂业务对象,都可摆放到房间,生成图纸,构建出最终的3D场景。
图纸用来描述机房内对象的外观,空间位置,以及必要的识别标志(ID)。机房内的对象主要包含房间,墙体,窗户,门,各类设备等对象,这些对象可以使用某个原型对象或者某个拼装对象描述,图纸内描述这些对象的位置、旋转角度等特性,满足机房内布局描述的需求。图纸是原型对象图纸和拼装对象图纸的组合体,由各种相关的对象实例片断组成。
以下是一份图纸的JSON描述:
{"primitives": [ { "size": {"x": 100, "y": 150, "z": 80}, "className": "mono.Cube", "rot": {"x": 0, "y": 0, "z": 0}, "ambient": [{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 },{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 } ], "color": [{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 },{"r": 1, "g": 1, "b": 1},{"r": 1,"g": 1,"b": 1},{"r": 1, "g": 1, "b": 1 }], "id": "E427D7FC289874506919A0852BF9506DA", "scale": { "x": 1,"y": 1, "z": 1}, "dt": ["images/chassis01.png", "images/chassis05.png", "images/metal09.png", "images/metal09.png", "images/metal09.png", "images/metal09.png"], "groupid": null, "transparent": [false, false, false, false, false, false], "types": ["phong", "phong", "phong", "phong", "phong", "phong"], "visible": [true, true, true, true, true, true], "opacity": [1, 1, 1, 1, 1, 1], "repeat": [[3, 3],[3, 3],[3, 3],[3, 3],[3, 3],[3, 3]], "type": "primitive", "shape": "PrimitiveModel" }, { "size": {"x": 17,"y": 3,"z": 2}, "className": "mono.Cube", "rot": { "x": 0, "y": 1.5707963267948966,"z": 0}, "id": "ECC87A75113A24DE5B4C7DE17086111EC", "scale": {"x": 1,"y": 1,"z": 1}, "dt": ["images/brush_metal.png", "images/brush_metal.png", "images/brush_metal.png", "images/brush_metal.png", "images/port/cent36f.png", "images/brush_metal.png"], "groupid": null, "transparent": [false, false, false, false, false, false], "types": ["basic", "basic", "basic", "basic", "basic", "basic"], "visible": [true, true, true, true, true, true], "opacity": ["1", "1", "1", "1", "1", "1"], "repeat": [ [1, 1],[1, 1],[1, 1],[1, 1],[1, 1],[1, 1]], "type": "primitive", "shape": "PrimitiveModel" }, { "size": {"x": 17,"y": 3, "z": 2}, "className": "mono.Cube", "rot": {"x": 0,"y": 1.5707963267948966, "z": 0}, "id": "EA54D15074B354C318472A5AC1D0267EB", "scale": {"x": 1, "y": 1,"z": 1}, "dt": ["images/brush_metal.png", "images/brush_metal.png", "images/brush_metal.png", "images/brush_metal.png", "images/port/cent36f.png", "images/brush_metal.png"], "groupid": null, "transparent": [false, false, false, false, false, false], "types": ["basic", "basic", "basic", "basic", "basic", "basic"], "visible": [true, true, true, true, true, true], "opacity": ["1", "1", "1", "1", "1", "1"], "repeat": [[1, 1],[1, 1], [1, 1],[1, 1],[1, 1],[1, 1]], "type": "primitive", "shape": "PrimitiveModel" } ], "assembles": [ { "id": "32C0CAA8-D1C8-4D15-B150-D6E728A00FF2", "children": [ { "id": "E427D7FC289874506919A0852BF9506DA", "OID": "main", "ishost": true }, { "id": "ECC87A75113A24DE5B4C7DE17086111EC", "pos": {"x": 52, "y": 62,"z": 19} }, { "id": "EA54D15074B354C318472A5AC1D0267EB", "pos": {"x": 52, "y": 62,"z": -14} } ], "assembleSize": {"x": 103,"y": 150,"z": 80}, "off": {"x": 1.5, "y": 0,"z": 0}, "type": "assemble", "shape": "AssembleModel", "label": "ss2" } ], "sketch": { "buildings": [], "equipments": [ { "id": "AA33A5DF6AB44D128870381ED4976972", "gid": "32C0CAA8-D1C8-4D15-B150-D6E728A00FF2", "position": [485, 75, 306.0034637451172], "rot": { "x": 0, "y": 0, "z": 0 }, "primitiveName": "ss2", "scale": [1, 1, 1] } ] }}
4.1 primitives
原型模型库。图纸中可以独立加载原型对象描述,独立组建原型模型库。如果不包含该属性或该属性内容为空,则表示使用mono的预定义原型模型库。
4.2 assembles
拼装模型库。图纸中可以独立加载拼装对象描述,独立组建拼装模型库。如果不包含该属性或该属性内容为空,则表示使用mono的预定义拼装模型库。
4.3 sketch
图纸对象,该对象用来描述房间内建筑物对象(building)和设备对象(equipment)。
4.3.1 building
building是建筑物对象集合,该属性取值为数组,数组内元素是专门的房间对象。
building的必需属性列举如下:
id:房间对象的编号。需要在图纸所有对象的编号中保持唯一性。
gid:指明描述房间模型的原型类型或者拼装类型的编号。
dshape:房间外轮廓轨迹。用来描述房间外轮廓的形状。取值类型为数组。3个数字一组,描述一个点。
children:房间内其他建筑物对象集合。取值为数组,数组内元素是房间内建筑物对象实例。里面也还可以包含房间对象。
building由多个建筑物对象构成(例如多个房间)。
建筑物对象的必需属性列举如下:
id:对象实例在整个房间场景中的唯一编号。用来满足mono加载场景的时候,能够根据该id快速检索设备或其他对象。
gid:声明该对象实例源于哪种模型(某个原型类型或者某个拼装类型)。取值必需取自于原型类型的id或者拼装类型的id。
建筑物对象的可选属性列举如下:
edgeIndex:表明本对象属于所在房间的哪一面墙。如果有此属性,mono会自动完成对象间组装动作(CSG, Constructive solid geometry)。
其他属性均衍生于对应的原型类型或者拼装类型(由gid指定),比如position,rotation,scale,texture,在本图纸的对象实例中出现的这些属性取值优先于模型中的属性取值。
position:表示实例对象在房间中的位置。
rotation:表示实例对象在房间中摆放的旋转角度。
scale:表示实例对象在房间中的缩放比例。
dt:表示实例对象采用的贴图资源的路径。
其他关于材质设置的属性,可以参考原型类型图纸内的相关描述。
4.3.2 equipment
equipment为设备类对象集合。该属性取值为数组,数组内是各种原型对象实例或者拼装对象实例,用来描述机柜,UPS,摄像头,配电柜等设备对象及布局。
必需属性:
id:房间对象的编号。需要在图纸所有对象的编号中保持唯一性
gid:指名描述房间模型的原型类型或者拼装类型的编号。
可选属性:
可选属性均衍生于对应的原型类型或者拼装类型(由gid指定),比如position,rotation,scale,dt,在本图纸的对象实例中出现的这些属性取值优先于模型中的属性取值。
position:表示实例对象在房间中的位置。
rotation:表示实例对象在房间中摆放的旋转角度。
scale:表示实例对象在房间中的缩放比例。
dt:表示实例对象采用的贴图资源的路径。
其他关于材质设置的属性,可以参考原型类型图纸内的相关描述。