Skip to content

Latest commit

 

History

History
1476 lines (905 loc) · 46.1 KB

documentation.md

File metadata and controls

1476 lines (905 loc) · 46.1 KB
Raw

Table of Contents

Quickvoxel Core

Quickvoxel Core is a pure Javascript toolkit for volumetric visualization of neuro files in the web browser. Everything that happens in Quickvoxel is strictly client-side, without the need of an active server (i.e. can run on a Github page)

Features:

  • Open and decodes NIfTI, MINC2, and MGH (experimental)
  • Display volume in world/subject coordinates to align registered volumes
  • Obliques
  • Can blend two volumes with different methods
  • Apply colormaps (44 available)
  • Adjust contrast and brightness

Requirement:

  • A modern web browser, compatible with WebGL2 (recent Chrome or Firefox)

Quickvoxel Core is backed by Pixpipe for decoding volume files and process the data, and by BabylonJS for the WebGL2 rendering.

Since this project is a core only, it is not bound to any frontend framework and needs to be sugar coated with some UI elements to provide a proper user interaction. You can find a minimal 10-lines example here (source).
A lot of additional methods to do more interesting things with Quickvoxel are implemented in the core and need to be tied to UI element to be fully usable. We'll see that in the following part.

Demo

(Most of the demos are less than 30 lines)

In addition QuickGui (source) is a more advanced project, developed for the #BrainHack2018 in Montreal. It uses some features of Quickvoxel Core with a simple and accessible UI.

API documentation

HERE

Install

Since Quickvoxel Core will most likely be used as a dependency, it can be used in multiple ways:

From a simple HTML page:

<!-- ES6 version -->
<script src="quickvoxelcore/dist/quickvoxelcore.es6.js"></script>

<!-- or ES5 version -->
<script src="quickvoxelcore/dist/quickvoxelcore.js"></script>

<!-- or ES5 minified version -->
<script src="quickvoxelcore/dist/quickvoxelcore.min.js"></script>

From another ES module:

npm install quickvoxelcore --save

Then, from your module:

// import the ES5 version
import quickvoxelcore from 'quickvoxelcore'

// or import the ES6 version
import quickvoxelcore from 'quickvoxelcore/dist/quickvoxelcore.es6.js'

How To

Getting started

To start, QuickvoxelCore needs an HTML5 canvas element:

<html>
<head>
  <title>QuickvoxelCore Test</title>

  <style>
  body {
    overflow: hidden;
    width: 100%;
    height: 100%;
    margin: 0;
  }

  #renderCanvas {
    width: 100%;
    height: 100%;
  }
  </style>

</head>
<body>
  <script src="../dist/quickvoxelcore.es6.js"></script>

  <canvas id="renderCanvas"></canvas>

  <script>
    let canvas = document.getElementById("renderCanvas")
    // ...
  </script>

</body>
</html>

No matter the way you pick (simple HTML page or ES module to be bundled), the features are accessible from the quickvoxelcore namespace:

let canvas = document.getElementById("renderCanvas")

let qvc = new quickvoxelcore.QuickvoxelCore( canvas )

The constructor quickvoxelcore.QuickvoxelCore(...) initializes several internal objects, three important ones can then be fetched:

  • the VolumeCollection
  • the RenderEngine
  • the CameraCrew
// ...

let qvc = new quickvoxelcore.QuickvoxelCore( canvas )

let volumeCollection = qvc.getVolumeCollection()
let renderEngine = qvc.getRenderEngine()
let camcrew = qvc.getCameraCrew()

Though, before launching your main app, if can be nice to check if QuickvoxelCore is running in a WebGL2 compatible environment. We have a function for that:

// test compatibility with WebGL2
if (!quickvoxelcore.webGL2()){
  alert( 'Quickvoxel Core cannot run here because this web browser is not compatible with WebGL2.' )
} else {
  // launch your app here
}

Interlude: the VolumeCollection

The VolumeCollection instance allows you to add new volume from file URL or from a file dialog. Once added, a volume file will automatically:

  • be given a unique ID within the collection
  • be parsed by Pixpipe
  • create a 3D texture for later display

The methods you will use from your VolumeCollection instance are:

  • .addVolumeFromUrl( String ) to add a volume from a URL
  • .addVolumeFromFile( File) to add a volume from a file in the local filesystem

In addition, VolumeCollection provides some events so that actions can be triggered during the lifecycle of a Volume:

  • volumeAdded is called when the volume is parsed and added to the collection. But its webGL texture is not ready yet! The callbacks attached to this event will have the volume object as argument.
  • volumeReadycalled after volumeAdded, at the moment the added volume has its WegGL 3D texture ready. At this stage, a volume is ready to be displayed.The callbacks attached to this event will have the volume object as argument.
  • volumeRemoved is called when a volume is removed from the collection with the method .removeVolume(id). The callbacks attached to this event will have the volume id (string) as argument.
  • errorAddingVolume is called when a volume failed to be added with .addVolumeFromUrl() and .addVolumeFromFile(). The callbacks attached to this event will have the url or the HTML5 File object as argument.

To each event can be attached multiple callbacks, they will simply be called successively in the order the were declared. To associate a callback function to an event, just do:

myVolumeCollection.on("volumeReady", function(volume){
    // Do something with this volume
})

In general, events are most likely to be defined from the main scope or from where you also have access to the RenderEngine instance.

VolumeCollection has plenty of methods, get the full description here. You may also want to check the documentation of the Volume class here.

Interlude: the RenderEngine

The RenderEngine instance is in charge of displaying the volume from the collection, once they are loaded. It also comes with all the features to rotates/translates the three orthogonal planes (referred as _planeSystem in the source), apply a colormaps, change brightness/contrast and deal with blending.

A RenderEngine can display only 2 volumes at the same time. The terminology used in the doc and source is

Two slots are available to mount volumes on the render engine. Those slots are called primary and secondary.

Then, some volume can be unmounted from a given slot and another volume from the volume collection can be mounted.

Rendering features such as colormap, contrast and brightness are associated to slots and not to volumes. This means, if you use the primary slot to mount a structural MRI and the secondary slot to mount a functional MRI, and then adjust the brightness/contrast/colormap of the secondary slot, mounting another fMRI instead of the one in place will not change those settings. Note: there are plans to add a additional volume for masking

RenderEngine has plenty of other methods, get the full description here

Interlude: The CameraCrew

The CameraCrew instance is automatically created at the instanciation of the QuickvoxelCore object. The purpose of the cameracrew is to provide an interface for camera and point of view manipulation.
The default camera in QuickvoxelCore is the perspective camera, but three additional orthographic cameras are provided:

  • one always facing the coronal plane
  • one always facing the sagittal plane
  • one always facing the axial plane

When the orthogonal planes are rotated, the orthographic cameras associated are also rotated to be always facing their respective plane. Each orthogonal camera can independently be zoomed in/out, translated and rotated.

To change the camera, the method .defineCamera() from the CameraCrew instance must be called. Though, multiple camera naming are possible:

  • after generic names: 'aOrtho', 'bOrtho' and 'cOrtho'. Those names where made generic because they don't imply a specific direction, even though before any rotation happen, aOrtho looks toward x, bOrtho looks towards y and cOrtho looks toward z.
  • after generic short names: 'a', 'b' and 'c', same logic as above
  • after their dominant axis names: 'x', 'y' and 'z'. This method is convenient because the names are dynamically associated with camera a, b and c depending on the dominant direction they are looking at and this association is reevaluated at every ortho plane rotation. For example, at first and before any plane rotation is performed, the x camera is the a camera. After some rotations, the a camera is probably no longer looking towards the x direction, then if we need the camera that looks toward x, we can no longer select the a camera for that. This is why this axis naming is important.
  • after the anatomical names, this is the same as dominant axis names but using a semantic neuroscientist are more used to: 'sagittal' (always toward x), 'coronal' (always toward y) and 'axial' (always towards z). Note that this relation between the anatomical names and the axis names is established by the MNI space conventions.

In addition to those names, two other are possible:

  • 'main' is the perspective camera
  • 'current' is the current camera being used

Of course the current keyword is not useful in the context of .defineCamera() but it is very handy when it comes to modifying the setting of a camera, i.e. no need to remember if we are changing the zoom setting of this or that camera, we are changing it on current.

Here is an example of how to change the camera:

// ...
let qvc = new quickvoxelcore.QuickvoxelCore( canvas )
let camcrew = qvc.getCameraCrew()

camcrew.defineCamera('coronal')
// ...

CameraCrew has plenty of other methods, get the full description here.

Mount a volume once it's ready

Here is how to load a volume from a URL (that has to comply with CORS, i.e. be in the same server as Quickvoxel)

// ...

volumeCollection.addVolumeFromUrl( "./data/structural.nii.gz" );

// mount the volume when it's ready!
volumeCollection.on("volumeReady", function(volume){
  // to mount the loaded volume on a specific engine slot.
  // (if a volume is already on this slot, it's unmounted and replaced by the new one)
  renderEngine.mountVolumeN( 0, volume )

  // OR, you can just mount it on the first slot available
  let couldMount = renderEngine.mountVolumeOnFirstEmptySlot( volume )

  if( !couldMount ){
    console.log("All volume slots are taken on the render engine, make some space before rendering this volume.");
  }
})

Alternatively, a volume can be loaded from you filesystem using a file dialog. Look at the example here. Then, the logic for mounting on a slot is the same.

Going Further

The RenderEngine object has a lot of methods that can be used to tweak your visualization. Do no hesitate to consult the API doc conserning the RenderEngine to make sure you use them properly.

Here is a list of what you can do:

  • show/hide a volume mounted on a slot
  • change the blending method between two volumes
  • mount/unmount a volume on/from a given slot
  • apply a colormap on a given slot
  • get the list of colormaps names and corresponding canvas for UI purpose
  • display a reversed colormap
  • change the brightness on a given slot
  • change the contrast on a given slot
  • change the time index of a volume on a given slot (time series)
  • rotate with a relative angle around the normal of a plane from the plane system (1 plane remains fixed)
  • translate along the normal of a plane from the plane system
  • apply an absolute rotation in world coordinates Euler angles
  • set the position of the plane system in absolute world coordinates
  • [experimental] change the position of the camera (incomplete, up vector needs to be set too)

TODO

In what is probably the order of future developments:

  • Add a link to source to each example
  • Add examples for multi camera usage
  • Masking capabilities (as a 3rd slot that has special features)
  • Raycasting capabilities, then we can get the position where the mouse pointer is hitting (and then the intensity in the volume, etc)
  • Try to build 3D textures without having to perform a conversion from float32 to uint8
  • Have a split view options with the 4 camera (3 orthos + 1 perspective)
  • Add a collection of meshes
  • Add a collection of point clouds
  • Check if WebGL2 is enabled
  • Add 3 cameras that are always facing each of the ortho planes
  • Gives the possibility to change the camera
  • Add method to automatically position a camera along the dominant X Y or Z
  • Add XYZ axis of a grid system to know where we are
  • Add a method to force the main (perspective) camera to follow the center of the plane system
  • Add events for when a volume asked to be loaded so that UI can display a spinner or something
  • Add anatomical names for camera ('sagittal', 'axial', 'coronal')

QuickvoxelCore

Build an instance of QuickvoxelCore to initialize Quickvoxel Core. Once constructed, the methods .getVolumeCollection() and .getRenderEngine() can be called to provide more features.

Parameters

  • canvasElem

getCameraCrew

Get the CameraCrew instance in order to perform some camera manipulations

Returns CameraCrew

getRenderEngine

Get the rendering engine to perform some 3D tasks, such as interacting with the view

Returns RenderingEngine

getVolumeCollection

Get the volume collection, to access to some features such as adding/removing a volume

Returns VolumeCollection

mountVolumeOnSlotN

Mount the volume of the given id on the slot with the given index on the rendering engine

Parameters

  • n Number the slot index
  • volumeId String the id of the volume within the collection

unmountVolumeFromSlotN

Unmount the volume from the slot n in the rendering engine. Note: this method is jsut a call to the rendering engine, since the volume itself is not needed to be unmounted.

Parameters

  • n [type] [description]

Returns [type] [description]

unmountVolumeWithId

[unmountVolumeWIthId description]

Parameters

  • id [type] [description]

Returns [type] [description]

VolumeCollection

Extends EventManager

The VolumeCollection is automatically initialized by the constructor of QuickVoxelCore. When the QuickVoxelCore object is created, the VolumeCollection can be fetched to perform actions directly on it.

A instance of VolumeCollection manages and identifies Volume instances. A Volume can be added to the collection using .addVolumeFromUrl() and .addVolumeFromFile(). Once one of these two method is called, a Volume instance is created (itself generating a 3D texture) and added to the collection with a given index.

VolumeCollection provides some events, so that actions can be triggered during the lifecycle of a Volume:

  • startAddingVolume is called when a new volume is about to be added. This event is convenient mostly for UI purpose so that we can for example show a loading spinner, that then will be hidden when the event volumeAdded or errorAddingVolume are called
  • volumeAdded is called when the volume is parsed and added to the collection. But its webGL texture is not ready yet! The callbacks attached to this event will have the volume object as argument.
  • volumeReadycalled after volumeAdded, at the moment the added volume has its WegGL 3D texture ready. At this stage, a volume is ready to be displayed.The callbacks attached to this event will have the volume object as argument.
  • volumeRemoved is called when a volume is removed from the collection with the method .removeVolume(id). The callbacks attached to this event will have the volume id (string) as argument.
  • errorAddingVolume is called when a volume failled to be added with .addVolumeFromUrl() and .addVolumeFromFile(). The callbacks attached to this event will have the url or the filename (if opened from file dialog) as argument.

To each event can be attached multiple callbacks, they will simply be called successivelly in the order the were declared. To assiciate a callback function to an event, just do:

myVolumeCollection.on("volumeReady", function(volume){
   // Do something with this volume
})

addVolumeFromFile

Add a volume to the collection from a file (most likely using a file dialog)

Parameters

  • file File a compatible volumetric file

addVolumeFromUrl

Add a volume file to the collection, using an URL

Parameters

getVolume

Get the Volume with the given id

Parameters

  • id String id of a Volume within the collection

Returns Volume the Volume instance with such id, or null if not found

getVolume

Get the volume of the given id

Parameters

  • id String unique id of the volume within the collection

Returns (Volume | null) the volume if existing, or null if not existing

getVolumeIds

Get the list of all volume ids available in this collection

Returns [type] [description]

removeVolume

Remove a volume fron the collection. If succesful, the event "volumeRemoved" is called with the id of the volume in argument

Parameters

  • id String id of the volume to remove

RenderEngine

Extends EventManager

The RenderEngine is automatically initialized by the constructor of QuickVoxelCore. The engine in in charge of the visualization part by initializing the WebGL environment, sending data to shaders, and updating them. Once the QuickVoxelCore object is created, the RenderEngine can be fetched to call methods from it directly.

Parameters

  • canvasElem DomElement a DOM object of a canvas

displayVolumeSlotN

Display of hide the volume hosted on the Nth slot

Parameters

  • n
  • d Boolean display is true, hide if false (optional, default true)

getBlendMethodList

Get the list of blending methods

Returns Array the list of strings, names of the blending methods

getColormapsCanvas

Get the canvas that represents a colormap. This is convenient when we want to display one or more colormap in the UI.

Parameters

  • cmName String name of the colormap to get

Returns Canvas The HTML5 Canvas object, ready to be appended to a div

getListOfColormaps

Get the list of colormaps available, by name

Returns Array Array of strings

getNumberOfVolumeSlots

Get the total number of volume slot in the reder engine (taken of not)

Returns Number

getPlaneSystemEulerAngle

Get the Euler angle of the plane system

Returns BABYLON.Vector3 The Euler angle

getPosition

Get the position of the center of the plane

Returns BABYLON.Vector3 position

getScene

Get the babylonjs scene object, because it's necessary to build textures in Volume

Returns BABYLON.Scene the scene

getSlotIndexFromVolumeId

Look if the volume with the given id is mounted in a slot

Parameters

  • id String id of the volume to look for

Returns Number index of the slot where the volume is mounted, or -1 if not mounted

getXDominantPlaneNormal

Get the the one of the 3 normal vectors of the _planeSystem that goes dominantly towards the X direction (Here "dominantly" is deducted by performing a dot product with [!, 0, 0])

Returns BABYLON.Vector3 the normal vector (as a clone)

getYDominantPlaneNormal

Get the the one of the 3 normal vectors of the _planeSystem that goes dominantly towards the Y direction

  • (Here "dominantly" is deducted by performing a dot product with [0, 1, 0])

Returns BABYLON.Vector3 the normal vector (as a clone)

getZDominantPlaneNormal

Get the the one of the 3 normal vectors of the _planeSystem that goes dominantly towards the Z direction. (Here "dominantly" is deducted by performing a dot product with [0, 0, 1])

Returns BABYLON.Vector3 the normal vector (as a clone)

isSlotTakenN

Get if the Nth volume slot is already taken or not.

Parameters

Returns Boolean true if already taken (or out of range), false if free

mountVolumeN

Mount a volume on the redering engine. This means the 3D texture attached to the given volume will be shown

Parameters

  • n Number the index of the slot to mount the volume on (most likely 0 or 1)
  • volume Volume the volume to mount

mountVolumeOnFirstEmptySlot

Mounts a volume in the first slot available. Will do nothing if no slot is free.

Parameters

  • volume Volume the volume to mount

Returns Boolean true if found an ampty slot to mount, false if could not mount it

resetPosition

Reset the rotation of the _planeSystem

rotateAroundXDominant

Rotate around the normal vector of the plane system that goes dominantly towards the X direction, from a relative angle (=adding rotation to the current system)

Parameters

rotateAroundYDominant

Rotate around the normal vector of the plane system that goes dominantly towards the Y direction, from a relative angle (=adding rotation to the current system)

Parameters

rotateAroundZDominant

Rotate around the normal vector of the plane system that goes dominantly towards the Z direction, from a relative angle (=adding rotation to the current system)

Parameters

setBlendingRatio

must be in [0, 1]. if closer to 0, the primary volume is more visible if closer to 1, the secondary volume is more visible

Parameters

setBlendMethod

Change the blending method. Note that this matters only when 2 textures are displayed. Available are:

  • quickvoxelcore.CONSTANTS.BLENDING_METHODS.ratio
  • quickvoxelcore.CONSTANTS.BLENDING_METHODS.added-weighted
  • quickvoxelcore.CONSTANTS.BLENDING_METHODS.multiply (default)

Parameters

  • method
  • m String method of blending

setBrightnessSlotN

Set the brightness value to apply on the volume of the slot n.

Parameters

  • n Number index of the volume slot
  • b Number value of the brightness, neutral being 0 (optional, default 0.)

setColormapOrientationSlotN

Set the orientation of the colormap used on the slot n, original or flipped

Parameters

  • n
  • orientation Number 0 for original, 1 for fliped

setColormapSlotN

Define the colormap the use on the texture loaded on the Nth slot

Parameters

  • n Number index of the volume slot (most likely 0 or 1)
  • cmName String name of the colormap. Get the list of names with .getListOfColormaps()

setContrastSlotN

Set the contrast value to apply on the volume of the slot n.

Parameters

  • n Number index of the volume slot
  • c (optional, default 1.)
  • b Number value of the cotrast, neutral being 1

setPlaneSystemEulerAngle

Set the Euler angle of the plane system

Parameters

setPosition

Update the position of the center of the _planeSystem in world coordinates. Not each position property have to be updated.

Parameters

  • position Object The new position (optional, default {x:undefined,y:undefined,z:undefined})

setPosition

Set the position of a given camera, by its id

Parameters

  • position Object ={x:100, y:100, z:100} - position of the camera (optional, default {x:undefined,y:undefined,z:undefined})
  • cameraId String the id of the camera

setTimeIndexSlotN

Set the time index of the volume mounted on the Nth slot. If the time index is higher than the duration of the volume, it will loop with a modulo

Parameters

showOriginAxes

Show of hide the axis that displays the origin. The 3 axis are 10mm long and always cross at (0, 0, 0) no matter the position of the ortho planes.

Parameters

  • b Boolean true will show, false will hide

showPlaneAxes

Show of hide the axis at the intersection of the orthogonal plane system. This set of 3 axis is always tied to the plane system and will translate and rotate with it.

Parameters

  • b Boolean true will show, false will hide

translateAlongXDominant

Translate the plane system along the dominant X direction

Parameters

  • d Number the distance to move along this vector (can be negative to move back)

translateAlongYDominant

Translate the plane system along the dominant Y direction

Parameters

  • d Number the distance to move along this vector (can be negative to move back)

translateAlongZDominant

Translate the plane system along the dominant X direction

Parameters

  • d Number the distance to move along this vector (can be negative to move back)

unmountVolumeN

Unmount the volume that is suposedly mounted on the slot N. this means the texture attached to the volume on slot N will no longer be visible.

Parameters

  • n [type] [description]

Volume

A Volume instance is a volumetric representation of some data that can be queried, displayed and identified.

  • To be queried, a Volume embeds a pixpipe.Image3DAlt
  • To be displayed, a Volume generates a WebGL 3D texture from the pixpipe.Image3DAlt
  • To be identified, a Volume instance has an id, unique in the VolumeCollection

Parameters

  • id
  • image3D

buildTexture

Build the texture corresponding to this volume. This requires a scene instance

Parameters

  • bjsScene [type] [description]

Returns [type] [description]

getAvaialableMatrices

Get a list of all available matrices for this volume, as strings

Returns Array

getId

Get the id of this volume

Returns String the id

getImage3D

Get the Pixpipe Image3DAlt object

Returns pixpipe.Image3DAlt The volume data as loaded by Pixpipe

getMatrix

Get the transformation matrix with the given name

Parameters

  • name String name of the transform (most likely "v2t" or "v2t_center")

Returns BABYLON.Matrix the matrix

getTexture3D

get the babylonjs texture3d object

Returns BABYLON.RawTexture3D the texture corresponding to this volume

getTimeLength

Get the number of time samples. fMRI (or diffusion) will have more than one while structural MRI will usually have only one.

Returns Number

getValue

Get the voxel value at the given world position. Note: the world coordinates are floating point and this method perform a lookup in voxel coordinates in the pixpipe.Image3DAlt data. Voxel coordinates being integer, no interpolation from worl to voxel is performed by this method. This just gives the value of the closest voxel.

Parameters

  • position Object position in world coordinates (optional, default {x:0,y:0,z:0})
  • time Number time index (makes sense only for time series) (optional, default 0)

Returns Number the voxel intensity

ColormapManager

An instance of ColormapManager is used by RenderEngine so generate colormaps to apply on the volume. Several types of colormaps are available, they are generated as pixpipe.Image2D, from which are made BABYLON.RawTexture (2D) and HTML5 Canvas. The texture is to be sent to the shader while the canvas can be used for UI purpose. Note that the original pixpipe.Image2D colormap is just used temporary and is not kept in memory.

Parameters

  • scene BABYLON.Scene the babylonjs scene (necessary to generate textures)
  • nbSamples Number number of samples generated per colormap (optional, default 512)

getColormapCanvas

Get a canvas element representing the given colormap. This canvas elem can directly be append to some div.

Parameters

  • name String the name of the colormap (default: 'default') (optional, default 'default')

Returns Canvas the Canvas object, of height 1px and width 512px (this depends on the default)

getListOfColormaps

Get the list of colormap names

Returns Array a list of Strings

CameraCrew

Extends EventManager

The CameraCrew provides four cameras (1 perspective and 3 orthographic) and a simplified API to control them. This include:

  • selection of the camera (for all 4 cams)
  • rotation (keep the target but change the up) - relative and absolute (only for ortho)
  • enlarging ratio - relative and absolute (only for ortho)
  • panning - relative and absolute (only for ortho)

As you can read, the fine tunings are not available with the perspective camera, this is because a mouse control is attached to it. These functions are accesible by giving the name of the camera as argument. Camera have names they were initialized with: 'aOrtho', 'bOrtho' and 'cOrtho', in addition to the 'main', which is the perspective cam. Those camera can also be called by their shorter names 'a', 'b' and 'c' and by there direction pointing names. The direction pointing names are names given dinamically to each camera depending on the direction they are pointing. Of course, those names are updated at every single rotation to make sure the direction pointing names remain relevant. Those names are 'x', 'y' and 'z' and they refer to the MNI space (or Talairach coordinates).

When using the CameraCrew in 'sinel view' mode (default, the view from only one camera is shown) then, the name 'current' can also be used to address the camera currenlty being used.

Parameters

  • renderEngine RenderEngine the renderEngine instance created by QuickVoxelCore
  • canvasElem Canvas the canvas DOM element used by QuickVoxelCore

angleOrthoCam

Define the absolute angle of the camera, considering the original position represents the origin. This rotation will modify the upVector but keep the direction the camera is pointing

Parameters

  • camName String name of the camera ('aOrtho', 'bOrtho', 'cOrtho')
  • angle Number angle in radian (0 is noon, +pi/4 is 3oclock, +pi/2 is 6oclock, -pi/4 is 9oclock)

defineCamera

Define what camera to use, by its name.

Parameters

  • camName String name of the camera ('main', 'aOrtho', 'bOrtho', 'cOrtho')

getCamTargetVector

Get the camera pointing normalized vector. Note: this vector complied to MNI space and Talairach coordinates regarding the 'x' axis, which means +x is on the right and -x is on the left (which is the opposite of OpenGL/WebGL conventions)

Parameters

  • camName String one of the name of the camera

Returns Object normalized vector {x: Number, y: Number, z: Number}

getCurrentCameraAnatomicalName

Get the anatomical name of the camera currently being used.

Returns String 'coronal', 'sagittal', 'axial' or 'main' (for perspective)

getCurrentCameraMainAxis

Get the dominant axis name of the camera currenlty in use

Returns String 'x', 'y', 'z' or 'main' (for perspective)

getListOfCameras

Get the list of camera names

Returns Array Array of strings, most likely ['main', 'aOrtho', 'bOrtho', 'cOrtho']

getOthoCamSpan

Get the span used on the given camera.

Parameters

  • camName String one of the name of an orthographic camera

Returns Number the span curetly being used by this camera

getXDominantOrthoCam

Get the ortho cam that points the most towards X direction. Note: due to the sucessive rotation potentially performed on this camera, it is possible that the name of this camera is not 'aOrtho'

Parameters

  • forceRecompute Boolean force recomputing is true, get last value from the LUT if false (default: false) (optional, default false)

Returns String the name of the camera pointing towards X direction

getYDominantOrthoCam

Get the ortho cam that points the most towards Y direction. Note: due to the sucessive rotation potentially performed on this camera, it is possible that the name of this camera is not 'bOrtho'

Parameters

  • forceRecompute Boolean force recomputing is true, get last value from the LUT if false (default: false) (optional, default false)

Returns String the name of the camera pointing towards Y direction

getZDominantOrthoCam

Get the ortho cam that points the most towards Z direction. Note: due to the sucessive rotation potentially performed on this camera, it is possible that the name of this camera is not 'cOrtho'

Parameters

  • forceRecompute Boolean force recomputing is true, get last value from the LUT if false (default: false) (optional, default false)

Returns String the name of the camera pointing towards Z direction

isUsingOrthoCam

Tell if the CameraCrew is currently using an orthographic camera in the 'single view' mode

Returns Boolean true is using an orthographic, false if using the perspective cam (and false if in multi view)

positionOrthoCam

Modify the absolute position of the camera on its axis. The default position is (0, 0) when the camera is centered on the ortho planes origin.

Parameters

  • camName String name of the camera ('aOrtho', 'bOrtho', 'cOrtho')
  • right Number horizontal position of the camera on its axis. Positive is right, negative is left (optional, default 0)
  • up Number vertical position of the camera on its axis. positive is up, negative is down (optional, default 0)

rotateOrthoCam

Rotates the given camera relatively to its current state. The camera will keep its direction, only the upVector will be changed (giving the impresion of image spinning)

Parameters

  • camName String name of the camera ('aOrtho', 'bOrtho', 'cOrtho')
  • angle Number relative angle in radian

setOrthoCamSpan

Update the span of a given orthographic camera. Bear in mind two things:

  • the span is doubled (once on each direction of the cam starting from the center)
  • the span given is horizontal and the vertical span will be deducted based on the ratio of the canvas.

Parameters

  • camName String name of the camera ('main', 'aOrtho', 'bOrtho', 'cOrtho')
  • span Number Like the FOV but for an orthographic camera. Must be positive.

translateOrthoCam

Moves the given camera relatively to its curent position. If the right and up come from screen coordinates, it is most likely that the alternative method .translateOrthoCamScreenAlign() is the one to use.

Parameters

  • camName String name of the camera ('aOrtho', 'bOrtho', 'cOrtho')
  • right Number moves to the right when positive, moves the the left when negative
  • up Number moves up when positive, moves down when negative

translateOrthoCamScreenAlign

Moves the given camera relatively to its curent position when using screen coordinates. Contrary to .translateOrthoCam(), this method takes in account the rotation of the camera (if any). This method is most likely the one to use when the right and up (aka. dx and dy) come from screen coordinates such as mouse/pointer.

Parameters

  • camName String name of the camera ('aOrtho', 'bOrtho', 'cOrtho')
  • right Number moves to the right when positive, moves the the left when negative
  • up Number moves up when positive, moves down when negative

zoomCamSpan

Multiply the enlargement of the ortho cam by a factor. A factor lower than 1 will make the image smaller, a factor higher than 1 will make the image bigger. Note: Under the hood, the camera span is multiplied by (1/factor).

Parameters

  • camName String name of the camera
  • factor Number ratio to multiply the cam span with

EventManager

The EventManager deals with events, create them, call them. This class is mostly for being inherited from.

on

Define an event, with a name associated with a function

Parameters

  • eventName String Name to give to the event
  • callback Function function associated to the even

getKeyFromValue

Gives the property name in the object that has the given value

Parameters

  • object Object an object that may contain a property associated with a specific value
  • value Object a value to look for

Returns String Name of the first property that has the given value. Or null if not found

webGL2

Know if the current environment is webGL2 compatible. Usage:

if (!quickvoxelcore.webGL2()){
  alert( 'Quickvoxel Core cannot run here because this web browser is not compatible with WebGL2.' )
} else {
  // call the main app
}

Returns Boolean true if compatible with WebGL2, false if not