4.3 场景和对象

场景库被设计用来控制场景画布以及其中的对象。

场景

这部分功能包括设置场景、添加查找对象和坐标转换工具。

scene.setenv (opttab)

根据opttab中的选项设置场景。无返回值。选项列表:

  • clear: 如果设置为 true，则清除场景中的所有对象。默认为 false。这可在脚本运行中使用，因为脚本开始运行时场景会被自动清理。
  • camtype: 将相机设置为透视 ("persp") 或正交 ("ortho") 投影。默认为 "persp"。
  • grid: 在xz平面 ("plane") 或单位球面上 ("sphere") 设置参考网格。默认为 "none"。
  • bgcolor: 设置背景颜色。可使用颜色字符串如 "black" 或 "#000000"。默认为 "white"。
  • rotspeed: 鼠标拖动旋转速度。默认为 1。
  • transpeed: 鼠标拖动平移速度。默认为 1。
  • near: 相机视锥近平面。默认为 2。
  • far: 相机视锥远平面。默认为 3000。

以下是设置相机投影和背景颜色的示例代码:

scene.setenv({camtype='ortho', bgcolor='black'})

scene.addobj (type [, opttab])

将一个特定类型和选项的对象添加到场景的(0, 0, 0)位置。返回这个对象。类型包括:

  • "points": 3D 离散点。使用以下选项: vertices, selectable, color, opacity, hcolor, size。
  • "polyline": 3D 折线。使用以下选项: vertices, selectable, color, opacity, hcolor, size。
  • "polygon": 2D 多边形，位于 xy 平面并朝 z(size) 方向挤压。使用以下选项: vertices, selectable, color, opacity, hcolor, size。
  • "mesh": 网格。使用以下选项: vertices, selectable, color, opacity, hcolor。
  • "box": 具有六个面的盒子。使用以下选项: width, height, length, selectable, color, opacity, hcolor。
  • "sphere": 球体。使用以下选项: radius, segments, selectable, color, opacity, hcolor。
  • "label": 始终朝向摄像机的文本标签。使用以下选项: text, font, selectable, color, opacity, hcolor, size。
  • "light": 始终指向(0, 0, 0)的方向光。使用不透明度选项。
  • ".json": Threejs JSON 文件。使用以下选项: selectable, hcolor。
  • ".gltf": GLTF 文件。使用以下选项: selectable, hcolor。
  • ".glb": GLB 文件。使用以下选项: selectable, hcolor。
  • ".geojson": GeoJSON 文件。使用以下选项: selectable, color, opacity, hcolor。

opttab 中的选项列表:

  • vertices: 一个数组，其中每三个数字代表一个三维点（x，y，z）。对于网格，每三个点组成一个三角形。法线遵循右手定则。默认为空。
  • width: 以x轴测量的盒子宽度。默认为1。
  • height: 以y轴测量的盒子高度。默认为1。
  • length: 以z轴测量的盒子长度。默认为1。
  • size: 厚度或宽度。默认为1。
  • radius: 球体的半径。默认为1。
  • segments: 对于球体网格的水平和1/2垂直分段。默认为32。
  • selectable: 如果为true，则可以选择该对象。默认为true。
  • color: 材质颜色，例如"red"或"#FF0000"。默认为"gray"。
  • hcolor: 如果被选中则高亮显示的颜色。默认为"red"。
  • opacity: 材质的透明度。默认为1。
  • name: 一个字符串，稍后可以被scene.getobj使用。默认为""。
  • text: 标签所使用的文本。默认为""。
  • font: 标签所使用的字体。默认为"Arial"。

以下是向场景添加对象的一些示例：

scene.setenv({grid='plane'})                                                 --设置一个平面网格
scene.addobj("points", {vertices={0,0,0, 5,5,5}, size=5})                    --添加两个大小为5的点
scene.addobj("polyline", {vertices={0,0,0, -2,3,5, 4,6,7}, color='blue'})    --添加一个蓝色折线
scene.addobj("polygon", {vertices={-1,-1,0, -1,1,0, 1,1,0, 1,-1,0}, size=0}) --添加一个二维多边形
scene.addobj("label", {text="hello", size=5})                                --添加一个标签
scene.render()                                                               --渲染场景

scene.getobj (name)

遍历场景，并返回第一个匹配名称的对象。相机和选定的对象可用"camera"和"selected"找到。

<a id='scene.tovector'> scene.tovector (radius, phi, theta) </a>

从球坐标转换返回 x、y、z。

<a id='scene.topolar'> scene.topolar (x, y, z) </a>

从向量返回球坐标：半径、phi、theta。

<a id='scene.render'> scene.render ([ms]) </a>

渲染场景并检查浏览器，类似于 [os.getready](4.2_operation_system.md#os.getready)，然后返回结果。可以通过 ms 参数控制渲染之间的间隔时间（毫秒）。

## 对象
这部分函数控制场景中的对象。请注意，调用 obj:func(args) 是 scene.func(obj, args) 的语法糖。

<a id='obj:getpos'> obj:getpos () </a>

返回对象的位置：x、y、z。

<a id='obj:setpos'> obj:setpos (x, y, z) </a>

设置对象的位置：x、y、z。如果对象是正交摄像机，则 z 也用作摄像机的缩放值。

<a id='obj:getrot'> obj:getrot () </a>

返回对象的旋转（弧度）：x、y、z。

<a id='obj:setrot'> obj:setrot (x, y, z) </a>

设置对象的旋转（弧度）：x、y、z。

<a id='obj:getscale'> obj:getscale () </a>

返回对象的缩放：x、y、z。

<a id='obj:setscale'> obj:setscale (x, y, z) </a>

设置对象的缩放：x、y、z。

<a id='obj:getchildren'> obj:getchildren () </a>

获取所有子对象并将它们放入一个表作为返回值。

<a id='obj:setchildren'> obj:setchildren (childtab) </a>

将表 childtab 中的所有对象设置为该对象的子对象。

<a id='obj:getparent'> obj:getparent () </a>

返回对象的父级对象。

<a id='obj:setparent'> obj:setparent ([parent]) </a>

设置对象的父级对象。对象可以没有父对象。

<a id='obj:getmat'> obj:getmat () </a>

获取对象的材质信息表。信息列表：
- type：材质类型字符串，比如<a href="https://threejs.org/docs/#api/en/materials/MeshBasicMaterial" target="_blank">"MeshBasicMaterial"</a>。
- map：纹理ID号。
- color：颜色字符串，例如"red"、"rgb(250, 0,0)"、"rgb(100%,0%,0%)"、"hsl(0, 100%, 50%)"、"#FF0000"、"#f00"。
- opacity：表示材质透明度的数字。

<a id='obj:setmat'> obj:setmat (opttab) </a>

从opttab中设置对象的材质。选项列表：
- type：材质类型字符串，比如<a href="https://threejs.org/docs/#api/en/materials/MeshBasicMaterial" target="_blank">"MeshBasicMaterial"</a>。
- map：纹理ID号或图像文件路径或URL，例如"map.jpg"。
- color：颜色字符串，例如"red"或"#FF0000"。
- opacity：表示材质透明度的数字。

<a id='obj:getvertices'> obj:getvertices () </a>

返回对象的几何体的顶点数组和索引数组（如果有）。

<a id='obj:setvertices'> obj:setvertices (vertices [, indices]) </a>

设置对象的几何体的顶点数组和索引数组（如果有）。

<a id='obj:getdata'> obj:getdata () </a>

返回存储对象的<a href="https://threejs.org/docs/#api/en/core/Object3D.userData" target="_blank">自定义数据</a>的表格。请参考[2.2 Searching for Countries](2.2_searching_for_countries.md)获取示例代码。

<a id='obj:setdata'> obj:setdata (datatab) </a>

将 datatab 中的 (key, value) 写入对象的自定义数据字段中。

obj:tojson (fpath)

将对象写入到指定路径的 Threejs JSON 文件中。

obj:delete ()

递归删除对象及其所有子对象。

本文使用ChatGPT翻译，如有遗漏请反馈open in new window。

Last Updated:
Contributors: huuhghhgyg