danzen/zim-three

Three is a helper module for the ZIM JavaScript Canvas Framework that makes it easy to include ZIM inside of three.js as an interactive texture.

In ZIM 015 we launched TextureActives. This is a system that reads raycast x and y and passes the data into ZIM instead of pointer position. Now anything that can be done in ZIM can be used as an interactive texture on any material of any mesh in three.js. This is beyond menus and also includes games, puzzles, interactive art and more!

See the ZIM 015 Features page for links to the promo video, VR examples and a half dozen general examples as well as video and article resources in ZIM and three.js forums.

Sample Code - Panel with Draggable Circle

Live Example | Forum Help

// ~~~~~~~~~~~~~~~~~~~~~~~
// ZIM

const panel = new TextureActive({
    width:W,
    height:H,
    color:light,
    corner:20
}).addTo();

// pressing the ALT T key will toggle between the 3D and 2D mode
// Usually we would use this during production then turn it off
// Here we add a logo that will also toggle when pressed	
TextureActive.makeLogo("light", true).loc(50,50,panel).tap(()=>{
  textureActives.manager.toggle();
});

new Circle(100, purple)
  .center(panel)
  .drag();    


// ~~~~~~~~~~~~~~~~~~~~~~~
// THREEJS

const three = new Three({
  width:window.innerWidth, 
  height:window.innerHeight, 
  cameraPosition:new THREE.Vector3(0,0,500),
  textureActive:true
});

const renderer = three.renderer;
const scene = three.scene;
const camera = three.camera;
const canvas = three.canvas;
const controls = new OrbitControls(camera, canvas);

// TEXTUREACTIVES
const textureActives = new TextureActives(panel, THREE, three, renderer, scene, camera, controls);

// if the object is a plane then we can use the makePanel
const canvasWindow = three.makePanel({
  textureActive:panel, 
  textureActives:textureActives, 
  curve:50,
  doubleSide:true
})
scene.add(canvasWindow);   

Here are the specific imports if desired:

import { Frame, Circle, TextureActive, TextureActives } from "zimjs"

Sample Code - Draw on Cube with Pen

Live Example | Forum Help

// ~~~~~~~~~~~~~~~~~~~~~~~
// ZIM

const paper = new TextureActive({
	width:500,
	height:500,
	color:black,
	corner:0,
	borderColor:white,
	borderWidth:2,
	backingOrbit:false
});

const pen = new Pen({color:series(white,purple), size:10, cache:false}).center(paper);
new MotionController({target:pen, type:"pressmove", container:paper});


// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// THREEJS

const three = new Three({
	width:window.innerWidth, 
	height:window.innerHeight, 
	cameraPosition:new THREE.Vector3(0,0,500),
	textureActive:true
});

const renderer = three.renderer;
const scene = three.scene;
const camera = three.camera;
const canvas = three.canvas;
const controls = new OrbitControls(camera, canvas);

// TEXTUREACTIVES
const textureActives = new TextureActives(paper, THREE, three, renderer, scene, camera, controls);


// if the object is not a plane then we use the CanvasTexture
const cubeGeometry = new THREE.BoxGeometry(300,300,300);
const cubeTexture = new THREE.CanvasTexture(paper.canvas);
const cubeMaterial = new THREE.MeshBasicMaterial({map:cubeTexture});
const cube = new THREE.Mesh(cubeGeometry, cubeMaterial);           
scene.add(cube); 
textureActives.addMesh(cube);

Here are the specific imports for the example above if desired:

import { Frame, MotionController, TextureActive, TextureActives, series, Pen } from "zimjs"

CDN

Usually we use ES Modules to bring in ZIM and if we want Three then we the code below - see the starting template at the top of the https://zimjs.com/code page.

import zim from "https://zimjs.org/cdn/016/zim_three";

NPM

This repository holds the NPM package so you can install from @zimjs/three on NPM. The ZIM package and three package must be installed to work. For three.js typings install @types/three

import zim from "zimjs"
import * as THREE from "three" 
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js"
import { Three } from "@zimjs/three"

NOTE: in the CDN version we import a half dozen controls and loaders. These can all be found in the NPM three directory under three/examples/jsm/ in controls, loaders and webxr. The ObjectControls can be found here https://www.npmjs.com/package/threejs-object-controls and brought into your app with npm install threejs-object-controls.

---

Below is an alternative to the TextureActive route above. It is older, perhaps simpler, and still has its uses. But we are mostly excited about TextureActives above!

Adding three.js inside of ZIM

This earlier original use-case overlays a three.js scene on the ZIM 2D canvas. In the example pictured above, the phone is a model in three.js. We are controlling color, rotation and zoom with ZIM components around the side. A drawback is either ZIM or three.js is interactive but not both. We did modify the OrbitControls of our ES6 module at https://zimjs.org/cdn/016/zim_three.js to work even when ZIM is interactive - but have not similarily adjusted a node module.

Older Examples

• https://zimjs.com/three/ - phone with controls
• https://zimjs.com/bits/view/three.html - cube with controls
• https://codepen.io/zimjs/full/qGPVqO - world with labels
• https://codepen.io/zimjs/full/abzXeZX - gallery

ZIM

See the ZIM repository at https://github.com/danzen/zimjs for information on ZIM and open source license, etc.