THREE.AugmentedConsole.js

A small tool to make development with three.js easier. It augments console.log: when what you log is something of three.js, its contents are added after the line as a table, a color as a swatch, and a texture or a material as a picture.

Open the demo GitHub npm

Every example in this page is running: under each piece of code there is what the library adds to the console for it. Open the console to see it there. The demo has a scene and all the commands to click.

How to use

Import the module in your three.js project, and the console is augmented. It's a single file with no dependencies, not even three.js: src/THREE.AugmentedConsole.js.

npm i three.augmented-console
import 'three.augmented-console';

Without npm or a bundler, copy the file and import it by its path. From then on, console.log, console.info and console.debug show more. The line is logged as you wrote it, and what the library adds comes after it. What it doesn't know is left as it is.

The things you log from the console of the browser have to be reachable from there. The variables of a module are not, so put the ones you want to inspect in window:

Object.assign( window, { THREE, scene, camera } );

Vectors, matrices and friends

The values of a vector, a quaternion or an euler, in a row.

console.log( camera.position );
console.log( cube.rotation );

A matrix, with its rows as rows. three.js stores them by columns, which is what makes them hard to read as they are.

console.log( cube.matrixWorld );

A color, with a swatch of it.

console.log( cube.material.color );

The things that are made of vectors have a row for each.

console.log( 'box', new THREE.Box3().setFromObject( cube ) );
console.log( new THREE.Frustum().setFromProjectionMatrix( camera.projectionMatrix ) );

A curve, a path or a shape shows what it is, and some points along it.

console.log( new THREE.CatmullRomCurve3( [
  new THREE.Vector3( - 1, 0, 0 ), new THREE.Vector3( 0, 1, 0 ), new THREE.Vector3( 1, 0, 0 )
] ) );

These are all the types of the math of three.js that are augmented:

Lists

A list of things of the same type is one table, with a row for each.

console.log( [ camera.position, cube.position, light.position ] );
console.log( [ new THREE.Color( 0xed6a5a ), new THREE.Color( 0xf4f1bb ), new THREE.Color( 0x9bc1bc ), new THREE.Color( 0x5ca4a9 ) ] );

What a Raycaster returns is a list too: the distance, the object, the point and the face of each intersection.

console.log( raycaster.intersectObjects( scene.children ) );

A list with things of different types, or with something that is not supported, is left as it is.

The objects of a scene

An object shows what it is, and where: its position, rotation and scale, and its position in the world.

console.log( cube );

Cameras and lights add what defines them.

console.log( camera );
console.log( light );

An object that has others shows them, folded. Click it to see what is in this scene.

console.log( scene );
console.log( scene.fog );

A geometry shows its attributes, and an attribute its first items.

console.log( cube.geometry );
console.log( cube.geometry.attributes.uv );

A texture shows its picture, and its settings by their names instead of the numbers that they are.

console.log( cube.material.map );

A material shows a swatch of each of its colors, its values and the maps that it has.

console.log( new THREE.MeshStandardMaterial( { color: 0xffb400, emissive: 0x301000, metalness: 1, roughness: .25 } ) );

And the uniforms of a shader, the type and the value of each one. A ShaderMaterial shows its own.

console.log( {
  time: { value: 1.5 },
  tint: { value: new THREE.Color( 0xfe5f55 ) },
  offset: { value: new THREE.Vector2( .5, .25 ) },
  map: { value: cube.material.map }
} );

The renderer shows how it is set up, and what the last frame took.

console.log( renderer );

Animations and skeletons are there too.

console.log( clip );

Nothing is computed or updated to show any of this. The position in the world is the one of the last time that the matrices were updated, and the bounds of a geometry are only there if something computed them.

All that is augmented from a scene:

Pictures of materials and render targets

A second module adds pictures that need three.js to be made. Import it after the first one. It needs three.js r155 or later, as three in your import map or bundler.

import 'three.augmented-console';
import { setRenderer } from 'three.augmented-console/materials';

With it, a material also shows a picture of a sphere that has it, as the material is at that moment. Change something, log it again, and see what it did.

console.log( cube.material );
cube.material.shininess = 100;
cube.material.color.set( 0x5ca4a9 );
console.log( cube.material );

The sphere is rendered in a small scene of its own, with a couple of lights and something to reflect, so it shows the material and not the lighting of your scene. A material that needs something that a sphere doesn't have, like vertex colors or custom attributes, won't look right.

A render target shows what it has, once the module has the renderer that can read it. It works for the targets that are RGBA, in bytes, half floats or floats, and the picture shows their linear values the way the screen would.

setRenderer( renderer );

console.log( target );

renderMaterial( material ) returns the picture of a material as a data URL, to use it somewhere else, and dispose() releases the renderer that makes them.

Your own types

To add a type, pass a function that tells if a value is of that type, and one that returns what console.table should show for it:

import { addSupportedType } from 'three.augmented-console';

addSupportedType(
  v => v instanceof Particle,
  v => ( { Particle: { x: v.x, y: v.y, age: v.age } } )
);

For something other than a table, addHandler takes the same test, and a function that is called with the value after it's logged. The ones added last go first, and one that returns true lets the next one that matches show the value too. logImages( [ { url, width, height } ] ) logs pictures in a line, and pictureOf( image ) makes one from an image, a canvas, a video or { data, width, height }.

Removing it

It's a tool for development, not something to ship with your page. To stop augmenting the console, and to start again:

import { install, uninstall } from 'three.augmented-console';

uninstall();
install();

The lines logged through the library show the library as their source in the console. To see where your code logged them, add the file to the ignore list of the DevTools.

Jaume Sanchez | clicktorelease.com | spite/THREE.AugmentedConsole.js