4.3 Scene and Object

The scene library is designed to control the scene canvas and the objects within it.

Scene

This part of the functions include setting up the scene, adding lookup objects, and coordinate transformation tools.

Set scene according to options in the opttab. No return. The list of options:

clear: Clear all objects in the scene if set it to true. Default is false. This can be used in the middle of a script, because the scene will be automatically cleaned up when the script starts running.
camtype: Set the camera to perspective (“persp”) or orthographic (“ortho”) projection. Default is “persp”.
grid: Set up a reference grid on the xz plane (“plane”) or the surface of the unit sphere (“sphere”). Default is “none”.
bgcolor: Set background color. A color string such as “black” or “#000000” can be used. Default is “white”.
rotspeed: The speed of rotation for mouse dragging. Default is 1.
transpeed: The speed of translation for mouse dragging. Default is 1.
near: Camera frustum near plane. Default is 2.
far: Camera frustum far plane. Default is 3000.

Here is a sample code for setting the camera projection and background color:

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

scene.addobj (type [, opttab])

Add an object to (0, 0, 0) of the scene with specific type and options. Return the object. The type includes:

“points”: Discrete points in 3D. Use these options: vertices, selectable, color, opacity, hcolor, size.
“polyline”: A 3D polyline. Use these options: vertices, selectable, color, opacity, hcolor, size.
“polygon”: A 2D polygon in xy plane and extruded in z(size) direction. Use these options: vertices, selectable, color, opacity, hcolor, size.
“mesh”: A mesh. Use these options: vertices, selectable, color, opacity, hcolor.
“box”: A box with six faces. Use these options: width, height, length, selectable, color, opacity, hcolor.
“sphere”: A sphere. Use these options: radius, segments, selectable, color, opacity, hcolor.
“label”: A text label that always faces towards the camera. Use these options: text, font, selectable, color, opacity, hcolor, size.
“light”: A directional light which always points to (0, 0, 0). Use the opacity option.
“.json”: A Threejs JSON file. Use these options: selectable, hcolor.
“.gltf”: A GLTF file. Use these options: selectable, hcolor.
“.glb”: A GLB file. Use these options: selectable, hcolor.
“.geojson”: A GeoJSON file. Use these options: selectable, color, opacity, hcolor.

The list of options in opttab:

vertices: A array in which each three numbers represent a 3D point (x, y, z). For a mesh, every three points compose a triangle. The normal is follow the right-hand rule. Default is empty.
width: For boxes measured in x axis. Default is 1.
height: For boxes measured in y axis. Default is 1.
length: For boxes measured in z axis. Default is 1.
size: Thickness or width. Default is 1.
radius: For spheres. Default is 1.
segments: For sphere meshes horizontal segments and 1/2 vertical segments. Default is 32.
selectable: The object can be selected if it is true. Default is true.
color: Material color such as “red” or “#FF0000”. Default is “gray”.
hcolor: Highlight color if selected. Default is “red”.
opacity: How transparent the material is. Default is 1.
name: A string can be used by scene.getobj later. Default is “”.
text: Used by label. Default is “”.
font: Used by label. Default is “Arial”.

Here is are some samples for adding objects to the scene:

scene.setenv({grid='plane'})                                                 --set a plane grid
scene.addobj("points", {vertices={0,0,0, 5,5,5}, size=5})                    --add two points with size of 5
scene.addobj("polyline", {vertices={0,0,0, -2,3,5, 4,6,7}, color='blue'})    --add a blue polyline
scene.addobj("polygon", {vertices={-1,-1,0, -1,1,0, 1,1,0, 1,-1,0}, size=0}) --add a 2D polygon
scene.addobj("label", {text="hello", size=5})                                --add a label
scene.render()                                                               --render the scene

scene.getobj (name)

Searches through the scene, and returns the first with a matching name. Camera and selected object can be found with “camera” and “seleted”.

scene.tovector (radius, phi, theta)

Return x, y, z from conversion of a spherical coordinates.

scene.topolar (x, y, z)

Return a spherical coordinates: radius, phi, theta from a vector.

scene.render ([ms])

Render the scene and check the browser like os.getready and return the same. The interval (milliseconds) between renders can be controlled via the ms parameter.

Object

This part of functions control the objects in the scene. Note that a call obj:func(args) is syntactic sugar for scene.func(obj, args).

obj:getpos ()

Return the position: x, y, z of the object.

obj:setpos (x, y, z)

Set the position: x, y, z of the object. If the object is a orthographic camera, the z is also used as the zoom value of the camera.

obj:getrot ()

Return the rotation(in radians): x, y, z of the object.

obj:setrot (x, y, z)

Set the rotation(in radians): x, y, z of the object.

obj:getscale ()

Return the scale: x, y, z of the object.

obj:setscale (x, y, z)

Set the scale: x, y, z of the object.

obj:getchildren ()

Get all child objects and put them in a table as the return value.

obj:setchildren (childtab)

Set all objects in the table childtab as children for the object.

obj:getparent ()

Return the parent of the object.

obj:setparent ([parent])

Set the parent of the object. The object can have no parent.

obj:getmat ()

Return the material information table of the object. The list of information:

type: A material type string, such as “MeshBasicMaterial”.
map: A texture id number.
color: A color string such as “red”, “rgb(250, 0,0)”, “rgb(100%,0%,0%)”, “hsl(0, 100%, 50%)”, “#FF0000”, “#f00”.
opacity: A number indicating how transparent the material is.

obj:setmat (opttab)

Set the material of the object from the options in opttab. The list of options: