ThreeJS

Linux, OSX:

Windows:

Code Coverage:

A Julia module to render graphical objects, especially 3-D objects, using the ThreeJS abstraction over WebGL. Outputs Patchwork Elems of three-js custom elements. Meant to be used to help packages like Compose3D render 3D output.

Click on any of the above examples to see the code used to draw them.

This can be used in IJulia and Escher to embed 3D graphics.

WebGL lets you interact with the GPU in a browser. As long as you have a modern browser, and it supports WebGL (Check this link to see if it does!), the output of this package will just work.

Pkg.add("ThreeJS")

Running Pkg.build("ThreeJS") fetches and installs the three-js webcomponents. This will be done automatically if you install ThreeJS.jl using Pkg.add("ThreeJS").

However, if you clone ThreeJS.jl (with Pkg.clone or otherwise), then these webcomponents must be installed manually into assets/bower_components. This is done to allow simultaneous development of both repositories.

API documentation can be found here.

For use in IJulia notebooks, using ThreeJS will set up everything including static files.

NOTE: If you are restarting the kernel, and doing using ThreeJS again, please reload the page, after deleting the cell where you did using ThreeJS.

Adding push!(window.assets,("ThreeJS","threejs")) in your Escher code, will get the static files set up and you can do 3D Graphics in Escher!

To use in a web server, you will need to serve the asset files found in the assets/ directory. Then adding a HTML import to the three-js.html file in the assets/bower_components/three-js will get you all set up! This is done by adding the following line to your HTML file.

<link rel="import" href="assets/bower_components/three-js/three-js.html">

For rendering Three-JS elements, all tags should be nested in a three-js tag. This can be done by using the initscene function. An outer div to put this in is also required and can be created by using the outerdiv function.

The code snippet below should get a scene initialized.

using ThreeJS
outerdiv() << initscene()

By default, a scene of 1000px x 562px is created. Support to change this will be added soon.

In Three-JS, meshes are objects that can be drawn in the scene. These require a geometry and a material to be created. Meshes decide the properties as to the position of where the object is drawn.

A mesh can be created using the mesh function taking the coordinates (x,y,z) as its arguments.

A geometry and a material element should be nested inside this mesh.

Geometries hold all details necessary to describe a 3D model. These can be thought of as the shapes we want to display.

ThreeJS.jl provides support to render the following geometry primitives:

• Boxes - box(width, height, depth)
• Spheres - sphere(radius)
• Pyramids - pyramid(base, height)
• Cylinders - cylinder(topradius, bottomradius, height)
• Tori - torus(radius, tuberadius)
• Parametric Surfaces - parametric(slices, stacks, xrange, yrange, function)
• Dodecahedron - dodecahedron(radius)
• Icosahedron - icosahedron(radius)
• Octahedron - octahedron(radius)
• Tetrahedron - tetrahedron(radius)
• Planes - plane(width, height)

These functions will return the appropriate geometry tags that are to be nested inside a mesh along with a material to render.

The geometry function is able to render custom geometries, which are specified by the vertices and the faces.

Materials are what decides how the model responds to light, color and such properties of the material.

A material tag is created by using the material function. Properties are to be passed as a Dict to this function.

Available properties are:

• color - Can be any CSS color value.
• kind - Can be lambert, basic, phong, normal, or texture(for texture mapping)
• texture - URL of image to be mapped as texture. Will be applied only if kind is set to texture.
• wireframe - true or false
• hidden - true or false
• transparent - true or false. Set to true to get proper rendering for transparent objects.
• opacity - Number between 0.0 and 1.0 (fully opaque).

Some helper functions to get these key value pairs is given in src/properties.jl.

mesh(0.0, 0.0, 0.0) <<
    [box(1.0,1.0,1.0), material(Dict(:kind=>"basic",:color=>"red")]

will create a cube of size 1.0 of red color and with the basic material.

Lines can be drawn by specifying the vertices of the line in the order to be joined. Lines can either be of "strip" or "pieces" kinds, which decide how the vertices should be joined. "strip" lines join all vertices, while "pieces" only joins the first and second, third and fourth and so on. Colors for the vertices of the lines can also be specified.

Lines are also meshes and has the properties of a mesh too, like position and rotation. Like meshes, they are a child of the scene.

Lines also require a material to decide properties of a line. The linematerial function can be used to do this and specify some properties for the line. The linematerial should be a child of the line element.

The line function can be used to draw lines.

line([(0.0, 0.0, 0.0), (1.0, 1.0, 1.0)]) <<
        linematerial(Dict(:color=>"red"))

Drawing mesh grids can be achieved by using the meshlines function. It creates a set of lines to form the grid and assigns colors to the vertices based on the z values.

If you are looking for a 2D grid, use the grid function. It creates a grid on the XY plane which can then be rotated as required.

No 3D scene can be properly displayed without a camera to view from. ThreeJS.jl provides support for a Perspective Camera view using the camera function.

This sets the position of the camera, along with properties like near plane, far plane, fov for field of view (in degrees), and aspect ratio.

The camera tag should be a child of the scene.

ThreeJS.jl provides support for 3 kinds of lighting.

• Ambient - ambientlight(color)
• Point - pointlight(x, y, z; color, intensity, distance)
• Spot - spotlight(x, y, z; color, intensity, distance, angle, exponent, shadow)

These tags should also be a child of the scene.

By default, ThreeJS adds TrackballControls to every scene drawn. This lets you interact with the scene by using the trackpad or mouse to rotate, pan and zoom.

You can use the reactive functionality provided by Escher to create Signals of the 3D graphic elements produced. These can let you create graphics that can be interacted with using UI elements like sliders. Try launching escher --serve (if you have Escher installed) in the examples/ directory and heading to localhost:5555/box.jl on the browser. You can see a box whose width, depth, height and rotation about each axes can be set and the box will update accordingly!

Currently, this functionality does not work in IJulia notebooks. Hopefully, this will be fixed soon and you can use Interact(https://github.com/JuliaLang/Interact.jl) to do the same in IJulia notebooks.

You can also do animations by using Reactive signals. See examples/rotatingcube.jl as an example. It is implemented in Escher, so running an Escher server from that directory and heading to localhost:5555/rotatingcube.jl should give you a cube which is rotating!

NOTE: Adding new objects to a scene will force a redraw of the scene, resetting the camera.

using ThreeJS
outerdiv() << (initscene() <<
    [
        mesh(0.0, 0.0, 0.0) <<
        [
            box(1.0,1.0,1.0), material(Dict(:kind=>"lambert",:color=>"red"))
        ],
        pointlight(3.0, 3.0, 3.0),
        camera(0.0, 0.0, 10.0)
    ])

Running the above in an IJulia notebook should draw a red cube, which is illuminated by a light from a corner.

For Escher, after the script above is run, the following code should give the same result.

using ThreeJS
using Compat

main(window) = begin
    push!(window.assets,("ThreeJS","threejs"))
    vbox(
        title(2,"ThreeJS"),
        outerdiv() <<
        (
        initscene() <<
        [
            mesh(0.0, 0.0, 0.0) <<
                [
                    ThreeJS.box(1.0, 1.0, 1.0),
                    material(Dict(:kind=>"lambert",:color=>"red"))
                ],
            pointlight(3.0, 3.0, 3.0),
            camera(0.0, 0.0, 10.0)
        ]
        )
    )
end