regl-project / regl-camera

A camera for regl

regl-camera

A basic reusable "turntable" camera component for regl. (Secretly just spherical coordinates.)

Example

const regl = require('regl')()
const camera = require('regl-camera')(regl, {
  center: [0, 2.5, 0]
})

const bunny = require('bunny')
const normals = require('angle-normals')

const drawBunny = regl({
  frag: `
    precision mediump float;
    varying vec3 vnormal;
    void main () {
      gl_FragColor = vec4(abs(vnormal), 1.0);
    }`,
  vert: `
    precision mediump float;
    uniform mat4 projection, view;
    attribute vec3 position, normal;
    varying vec3 vnormal;
    void main () {
      vnormal = normal;
      gl_Position = projection * view * vec4(position, 1.0);
    }`,
  attributes: {
    position: bunny.positions,
    normal: normals(bunny.cells, bunny.positions)
  },
  elements: bunny.cells
})

regl.frame(() => {
  camera((state) => {
    if (!state.dirty) return;
    regl.clear({color: [0, 0, 0, 1]})
    drawBunny()
  })
})

Install

npm i regl-camera

API

Constructor

var camera = require('regl-camera')(regl[, options])

module.exports of regl-camera is a constructor for the camera. It takes the following arguments:

• regl is a handle to the regl instance
• options is an object with the following optional properties:
  • center which is the center of the camera
  • theta the theta angle for the camera
  • phi the phi angle for the camera
  • distance the distance from the camera eye to the center
  • up is the up vector for the camera
  • fovy is the field of view angle in y direction (defaults to Math.PI / 4)
  • near is the near clipping plane in z (defaults to 0.01)
  • far is the far clipping plane in z (defaults to 1000.0)
  • mouse set to false to turn off mouse events
  • damping multiplier for inertial damping (default 0.9). Set to 0 to disable inertia.
  • noScroll boolean flag to prevent mouse wheel from scrolling the whole window. Default is false.
  • element is an optional DOM element for mouse events (defaults to regl canvas element)
  • rotationSpeed the rotation interactions (default: 1)
  • zoomSpeed the zoom interactions (default: 1)
  • renderOnDirty boolean flag to control whether scene is only rendered when the camera state has changed. If true, render can be triggerd at any time by setting camer.dirty = true. If false, dirty state can still be detected and used through context.dirty.

Command usage

camera(block)

regl-camera sets up an environment with the following variables in both the context and uniform blocks:

Variable	Type	Description
view	mat4	The view matrix for the camera
projection	mat4	The projection matrix for the camera
center	vec3	The center of the camera
eye	vec3	The eye coordinates of the camera
up	vec3	The up vector for the camera matrix
theta	float	Latitude angle parameter in radians
phi	float	Longitude angle parameter in radians
distance	float	Distance from camera to center of objective
dirty	boolean	Flag set to true when camera state has changed

Note These properties can also be accessed and modified directly by accessing the object, though at the moment you will need to manually set camera.dirty = true if relying upon renderOnDirty

License

(c) 2016 Mikola Lysenko. MIT License

regl-camera's Issues

Support touch events

Touch events on mobile aren't being captured by the underlying mouse-change package used by regl-camera.

Could potentially be solved by replacing use of mouse-change with https://interactjs.io/docs which abstracts click/touch and also supports gestures which would enable adding pinch to zoom on mobile

npm module outdated

The most recent version on npm is missing at least one PR. Is it possible to publish the latest to npm? Thanks!

Gimbal lock makes everything blank

If you rotate the view to the top, you immediately get gimbal lock and NaNs and the view goes blank. Perhaps a better behavior would be to clip phi to pi / 2 - epsilon so at least the view doesn't disappear.

Support for other values for "front" vector

Nice library, great work! However, I seem to have hit a snag in my usage.

I am setting up a view where Z-axis points up, and X/Y describe a horizontal plane that the viewer is looking at from above. I specified the up vector to be [0, 0, 1], correspondingly, but that's when mouse rotation stopped working: both horizontal and vertical mouse movement only change the "theta" angle. Seems like that is because the Z-axis is hardcoded to also be the "front"? Where I need it to be [0, 1, 0] instead.

In other words, since the options accept an up vector, it would be nice to set the front as well.

Thanks!

injects stale values into context - not live-bound to cameraState

doc says values likes theta, phi, distance are injected into context, but they are stale
https://github.com/regl-project/regl-camera/tree/0182e4ef8511f987925ada18c1eb63d349e7fd6c#camerablock

this is because cameraState values are copied once on camera create

regl-camera/regl-camera.js

Line 140 in 0182e4e

context: Object.assign({}, cameraState, {

How do I update the camera externally?

As the title says I can't figure out how I'm supposed to update the camera externally from my consuming code. From the README it seems like you're supposed to just mutate properties of the camera function or on the arguments returned in the callback block, but in all my attempts the properties are all mostly undefined and updating them doesn't have any effect.

Looking at the source it seems like this is due to the fact all of these externally exposed properties are being copied by value rather than reference.

I have found a work-around for this by exposing the updateCamera method for external code to call which is available in my fork, but I wanted to know if there's a "correct" way to do this without modifying the library, or is this module intended to be purely internal state?

-

(Sorry, wrong repo)

support pan

This is a great simple camera but pan functionality would be very useful.

incompatible with headless-gl

node_modules/regl-camera/regl-camera.js:32
  element.addEventListener('mousewheel', function (e) {
         ^

TypeError: Cannot read property 'addEventListener' of undefined

Feature request: inverse view

Option to disable inertia (or increase threshold)

I like my mouse generally fast. That means that 90% of my interactions with a regl camera get intercepted by inertia, which makes it rather difficult to control. Would a PR to disable the inertia feature or at least set a higher threshold be desirable?