Getting started
Two short walk-throughs to get you going: first a simple 3D scene, then a live dashboard of 3D charts. Every step is a complete program running right beside the example code so you can see exactly what each line does. You can copy any step as a single HTML file, or open it in CodePen and play with it there. It should take about fifteen minutes from start to finish.
Setting up
There's nothing to install! A single HTML file is all you need. An import map tells the
browser where to find 'phoria2' (here it's a CDN, pinned to version
), and then your code imports from it just as it would from npm. Here's
the first step below as the complete file:
Save it as index.html and open it in your browser. The Copy as one page button
on every step gives you a file just like this one, ready to run.
Part 1: A first scene
1. A box on the page
A View draws into a canvas - you can pass it the element itself, or a CSS selector to
find it. Whatever it draws lives in its scene. A Mesh is a shape (its
geometry) with a look (its material), and the material is just a plain
object of options.
You'll notice there's no camera or light in the code, yet there's a lit box on screen. When you don't give it a camera, the View looks at the scene from the front, slightly to the right and above, and fits everything in. With no lights, it lights the scene itself and mentions this in the console. The View also only draws when something changes - so once this still picture is on screen it costs nothing to render until it changes - this is different to most 3D libraries.
2. Light and motion
Setting orbit: true lets you move the view around: drag to orbit, right-drag to pan
and scroll to zoom. A DirectionalLight shines like the sun, with all its light going the
same way - its direction is the way the light travels, which here is down and away from
you. scene.add() hands back whatever you added, so you can keep hold of it for later.
view.start() calls your function once every frame, passing in the seconds since the
last one (dt). Multiplying your movement by dt keeps the speed the same on
any screen, however fast it refreshes - here the cube turns at 0.6 radians a second.
3. Materials, a floor and shadows
Positions are in metres, with Y pointing up. roughness goes from a perfect mirror at
0 to completely matte at 1, and metalness: 1 turns a material into metal, which reflects
its surroundings tinted by its own colour. environment: 'studio' gives it a built-in
photo studio to reflect (you can use your own .hdr file too). Shadows need three things:
the light casts them, the shapes cast them, and the floor receives them.
4. Labels
A Label is an HTML element tracking a point in 3D. That means it's sharp at any size,
you can select its text and you can style it with CSS - this step has a little CSS in its HTML to show
that. Because it's added to the cube rather than the scene, the label follows the cube wherever
it goes and its position is measured from the middle of the cube.
5. Hover and click
highlight tints whatever is under the pointer, and tooltip is given a
hit - a description of what's under the pointer - and returns what to show for it.
view.on('click') gets a hit too, or null if you clicked on empty space. The
floor is set to pickable: false, so the pointer passes straight through it.
6. A shader hook
For anything the material options can't do, shader lets you run a few lines of your
own GLSL inside phoria2's shader. Here the vertex hook moves each point of the floor up
and down into ripples (more segments gives it more points to move), and bends its normal
n to match, so the lighting and shadows follow the ripples too. uTime is
the View's clock, and a hook that uses it keeps the scene moving without you writing a frame loop.
Hooks can change colours as well - the reference lists everything each hook can use, along with some
recipes you can copy.
Part 2: A chart dashboard
1. A bar chart from rows
chart(), from phoria2/charts, turns rows of data into a chart, complete
with axes, ticks, a grid, a legend and tooltips. You tell it which fields to use: x and
z for the rows of bars, y for their height and color for their
colour, and tooltip: true shows every field when you hover over a bar.
view.frame() moves the camera so the chart fits nicely in view.
A chart is just an ordinary node in the scene, so you can orbit around it, hover over the bars, and click the swatches in the legend to hide or show a region.
2. Live data
chart.update(rows) moves the bars to their new figures. A field can also be given as
an object, with a title and a format for the axis and tooltips - here the
sales figures are in thousands of pounds.
The View draws while the bars are moving, then stops again until the next update - so a dashboard left open costs almost nothing in between refreshes.
3. A dashboard of views
Each tile is its own View on its own canvas, laid out with ordinary CSS grid, and you
can have as many as you like on a page. Browsers only allow around 16 WebGL contexts, so phoria2
gives the first four their own and draws the rest through one shared context - each one is still
its own canvas though. framing: 'both' keeps the whole chart visible in its tile,
whatever shape the tile ends up. This happens automatically, you just use a canvas for each.
All three charts are made from the same rows - only the mark changes, to bars, lines
and areas stacked up to a total. A small tile() function saves writing the same setup
three times.
4. Linked views
Clicking a bar gives you a hit whose datum is the row behind that bar.
chart.filter() only shows the rows a function keeps, so clicking a bar narrows the other
two tiles down to its region, and clicking on empty space passes null so they show every
region again. The filter keeps working as the data updates.