xyz is a package that supports interactive 3D viewing and editing, building on the GPU framework, which in turn is based on WebGPU, which is available on all non-web platforms and is gaining wider browser support: WebGPU. The full API documentation is at xyz, and the xyz example provides a good working example to start from.
Here is a screenshot of the xyz example:
Elements
Solid
The xyz.Solid type is the main 3D object that renders a visible shape. Its shape comes from a xyz.Mesh, which is a potentially shared element stored in a library and accessed by unique names. The other visible properties (e.g., Color, how Shiny or Reflective it is, etc) are defined by the xyz.Material properties. It can also have a xyz.Texture (also referenced by unique name from a shared library) that is an image providing a richer more realistic appearance.
The xyz.Pose values on a Solid (and all other xyz nodes) specify the 3D position and orientation of the object.
Scene
The 3D scenegraph and the shared Mesh and Texture libraries are managed by the xyz.Scene node, along with the Lights, Camera and a Library of loaded 3D objects that can be referenced by name. The scene of objects is rooted in the Children of the Scene.
Mesh and Texture elements use the “Set / Reset” approach, where Set does add or update, based on unique name id, and if there are large changes and unused elements, a Reset can be used to start over. After the GPU is up and running (e.g., after the main app window is opened), changes take effect immediately, but everything can be configured prior to that, and they will all be applied when the GPU is activated.
Group
The xyz.Group is a container of other elements, and typically visible objects are actually Groups with multiple different subgroups and finally Solid elements. Groups are also used for optimizing the rendering, such that any Group that is fully out of view will be skipped over entirely: therefore, it is a good idea to create spatially-organized groups at different scales, depending on the overall scene size and complexity.
Resources
Meshes are exclusively defined by indexed triangles, and there are standard shapes such as Box, Sphere, Cylinder, Capsule, and Lines (rendered as thin boxes with end points specified), e.g.,:
Textures are loaded from Go image files, e.g.,:
The Scene also contains a Library of uniquely named “objects” (Groups) which can be loaded from 3D object files in the Wavefront .obj format, and then added into the scenegraph as needed, e.g.:
The library objects are Cloned into the scenegraph so they can be independently configured and manipulated there. Because the Group and Solid nodes are lightweight, this is all very efficient.
Lights
At least one light must be added to make everything in the scene visible. Four different types are supported.
The lights use standard light types via the xyz.LightColors to specify the light color, e.g., xyz.DirectSun is the brightest pure white color.
The xyz.Ambient light is the simplest, providing a diffuse uniform light that doesn’t come from any given direction:
The xyz.Directional light shines toward the origin (position 0,0,0) from wherever it is placed, and only the vector from this position to the origin matters: distance is not a factor:
The xyz.Point light is like Directional except that it has decay factors as a function of distance:
The xyz.Spot light is the most complex, with an angular decay and a angular cutoff, light a classic desk lamp.
If you want a visible representation of the light in the Scene, you can add that using whatever Solid you want.
Camera
The xyz.Camera determines what view into the 3D scene is rendered, via its Pose parameters, e.g.,:
xyzcore
The xyz/xyzcore package provides two core.Widget wrappers around the xyz.Scene:
• xyz/xyzcore.SceneEditor provides full object selection and manipulation functionality, and a toolbar of controls.
• xyz/xyzcore.Scene just displays the scene, and supports mouse-based zooming and panning of the camera.
Events
The GUI interactions are managed by functions such as xyz.Scene.MouseScrollEvent, xyz.Scene.SlideMoveEvent, and xyz.Scene.NavKeyEvent, which are connected to the core event management system in xyzcore.Scene.
There are also other helper functions in xyz/events.go.
Updating, Making, Rendering, etc
xyz is based on the tree infrastructure, documented in Plan, for flexible ways of building and updating 3D scenes.
The Update() method on Scene (or any node) will update everything based on Maker and Updater functions that have been installed.
The Render() method on the Scene will render to a gpu.RenderTexture that is an offscreen rendering target. Use RenderGrabImage() to get the resulting image as a Go image. The xyzcore.Scene automatically manages the updating and rendering consistent with the core standard mechanisms, using an optimized direct rendering logic so the resulting rendered image stays on the GPU and is used directly.
Lines, arrows, etc
There are handy functions in xyz/lines.go for creating complex line-based shapes, including those with arrow heads. These include Mesh functions for making the meshes, and Init functions that initialize a Group or Solid with line shapes.
To make a set of lines:
To make a line with arrow heads: