params.json

{
  "name": "Veri",
  "tagline": "Enables functionality for VR videos, including 360, stereoscopic, 3D objects, interaction and control, crosshairs, and ambisonic audio.",
  "body": "# veri -  Virtual Reality Video Player #\r\n\r\nThis library makes it easy to play 360 and VR videos from a browser.  It provides the functionality which\r\nis often useful with 360/VR videos, such as setting up a canvas and a THREE.js environment\r\nwhich renders a 360/VR video; headset movement detection; ambisonic audio interface; hand-held controller interface and rendering; rendering of 3D OBJ\r\nobjects over the video layer, or inside the VR scene, which can serve as buttons, crosshairs, and lots more.\r\n\r\n### Worked Example ###\r\n\r\nFor basic usage, you must include the veri library and a video element:\r\n\r\n```html\r\n<script src=\"../dist/veri.js\"></script>\r\n<video id=\"veri\" crossorigin=\"anonymous\"  autoplay loop src=\"https://threejs.org/examples/textures/MaryOculus.webm\" style=\"display: none; width: 100%; height: 100%; background: black;\" />\r\n```\r\n\r\nThen you setup the VR options and start playing:\r\n\r\n```javascript\r\nvar veri = new Veri();\r\n\r\nveri.setup({\r\n    controls: \"auto\",\r\n    vrEnabled: true,\r\n    stereoscopic: \"left-to-right\",\r\n    initializeCanvas: true,\r\n    camera: {\r\n        fov: 90,          // wider -> narrower  (10..100)\r\n        aspect: window.innerWidth / window.innerHeight,\r\n        near: 0.1,\r\n        far: 1000,\r\n        direction: Veri.vec3(0, 0, -1)\r\n    },\r\n    renderer: {\r\n        width: window.innerWidth,\r\n        height: window.innerHeight\r\n    },\r\n    light: {\r\n        position: Veri.vec3(2, 2, 2)\r\n    }\r\n});\r\n\r\nveri.start();\r\n```\r\n\r\n\r\n### For True VR ###\r\n\r\nTrue VR experiences require a VR headset, such as HTC Vive, Oculus Rift, or Samsung Gear.  This implies two camera perspectives will be rendered.  The implementation is based on WebVR and Three.js.\r\n\r\nFor HTC Vive, there is an OBJ resource available which represents the two HTC Vive controllers, along with texture and spec files, assumed to be in the subdirectory **resources/models/obj/vive-controller/**\r\n\r\n### Functionality List ###\r\n\r\nThe VR plugin supports the following:\r\n\r\n* setup a [THREE js](http://threejs.org/) canvas\r\n* setup a scene: camera, lighting, walls\r\n* setup VR (requires VR hardware)\r\n* setup stereoscopic VR, which provides depth\r\n    * side-by-side frames supported\r\n    * top-to-bottom frames supported\r\n* setup a monoscopic 360 video\r\n* setup interaction objects using an overlay.  Objects are 3D objects and their textures, provided in OBJ file format.\r\n    * overlay fixed in the camera's reference frame\r\n    * overlay fixed in the video's reference frame\r\n* interaction handling\r\n    * device-driven movement (rotation of mobile device, movement of headset)\r\n    * panning with mouse drag for 360 video\r\n    * zoom in/out with mouse wheel for 360 video\r\n    * limit interaction space to avoid overlap with control bar on top and bottom\r\n    * keyboard control\r\n* RayCasting - detect which object was clicked in the scene\r\n* audio implemented by [jsAmbisonics](https://github.com/polarch/JSAmbisonics)\r\n    * positional audio sources\r\n    * ambisonic audio sources\r\n* crosshairs - a small object at the center of the field of vision for pointing to targets in the VR scene\r\n    * default circle animation\r\n    * supports sprite animation\r\n* general event emitter functionality\r\n\r\nThe following are not yet supported:\r\n\r\n* iPhone 360 video\r\n* debugging helpers\r\n    * show axis\r\n    * show fps\r\n\r\n### Complete annotated list of configuration options ###\r\n\r\n```javascript\r\nveri.setup({\r\n\r\n    // controls:\r\n    // \"auto\" will auto-detect.  Can be set to \"device\", \"mouse\"\r\n    controls: \"auto\",     // auto-detect\r\n\r\n    // vrEnabled:\r\n    // if set to true, and VR hardware is found, then the\r\n    // the video is rendered on the VR hardware, using WebVR\r\n    vrEnabled: true,\r\n\r\n    // stereoscopic:\r\n    // can be set to \"side-by-side\" if the eye frames\r\n    // are next to each other, or \"top-to-bottom\"\r\n    // monoscopic videos don't set this.\r\n    stereoscopic: \"side-by-side\",\r\n\r\n    // debug:  (OPTIONAL)\r\n    // here you can request display of axis or fps\r\n    debug: {\r\n        showAxis: false,\r\n        showFPS: false\r\n    },\r\n\r\n    // camera:\r\n    // position and camera settings.  For more information refer to THREEjs\r\n    camera: {\r\n        pos: Veri.vec3(0, 0, 0),\r\n        fov: 35,          // wider -> narrower  (10..100)\r\n        aspect: window.innerWidth / window.innerHeight,\r\n        near: 0.1,\r\n        far: 1000,\r\n        direction: Veri.vec3(0, 0, -1) // the lookAt vector3\r\n    },\r\n\r\n    // crosshairs:\r\n    // provide a list of targets that the crosshairs can activate\r\n    // each target must have a name and direction\r\n    // hitRadius - radians offset which is considered\r\n    //     part of the target\r\n    // hitTime - time in milliseconds until the target is considered \"clicked\"\r\n    // sprite - optional sprite for animation.  Include src,\r\n    //     columns, rows, and count.\r\n    //     If not specified\r\n    //     then a small ring is used to indicate selection progress\r\n    //\r\n    // Note: use the event emitter to determine crosshairs state.\r\n    crosshairs: {\r\n        targets: [ {\r\n            name: \"play\",\r\n            direction: Veri.vec3(-1, 0, -1)\r\n        }, {\r\n            name: \"stop\",\r\n            direction: Veri.vec3(-1, 0, -1)\r\n        }],\r\n        hitRadius: 0.1,\r\n        hitTime: 6000,\r\n        sprite: {\r\n            src: \"../resources/sprite/all2048.png\",\r\n            columns: 16,\r\n            rows: 13,\r\n            count: 208\r\n        }\r\n    },\r\n\r\n    // renderer:\r\n    // specify width and height\r\n    renderer: {\r\n        width: window.innerWidth,\r\n        height: window.innerHeight\r\n    },\r\n\r\n    // sphere360: (OPTIONAL)\r\n    // specify parameters for the rendering sphere.  \r\n    sphere360: {\r\n        radius: 500,\r\n        hide: false\r\n    },\r\n\r\n    // audio: (OPTIONAL)\r\n    // supports both positional and ambisonic audio encoded in B-format\r\n    // attributes:\r\n    //     src: url of the source audio file\r\n    //     type: can be \"positional\" or \"ambisonic\"\r\n    //     positional: provide a position vector (for positional type)\r\n    audio: {\r\n        type: \"positional\",\r\n        src: \"https://upload.wikimedia.org/wikipedia/commons/2/2a/20091104_Alisa_Weilerstein_and_Jason_Yoder_-_Saint_Sa%C3%ABns%27_The_Swan.ogg\",\r\n        position: Veri.vec3(0, 0, -10)\r\n    }\r\n\r\n    // objects: (OPTIONAL)\r\n    // specify a dictionary of objects which should be rendered.  These typically\r\n    // would be the buttons that the user can click or tap on.  Each object should\r\n    // provide:\r\n    //     resource: a relative path for the OBJ file\r\n    //     movesWithCamera: true if the object must remain fixed in the camera's frame\r\n    //         as the camera moves about\r\n    //     position: if the object does not move with the camera, this is a fixed\r\n    //         position in the scene space.  If it does move with the camera, this\r\n    //         becomes a 3-vector relative to the camera.\r\n    //     color: provide a hex color\r\n    //     handler: function that should be called when the object is clicked.  The name\r\n    //         of the object will be passed to the handler, so the same handler can be\r\n    //         specified on all of the objects if desired.\r\n    objects: {\r\n        stopButton: {\r\n            resource: 'resources/obj/s-stop.obj',\r\n            position: Veri.vec3(-1, 0, -5),\r\n            color: 0xc8955c,\r\n            movesWithCamera: false,\r\n            handler: clickHandler  \r\n        },\r\n        goButton: {\r\n            resource: 'resources/obj/s-rev-fwd.obj',\r\n            position: Veri.vec3(1, 0, -5),\r\n            color: 0xc8955c,\r\n            movesWithCamera: false,\r\n            handler: clickHandler\r\n        }\r\n    },\r\n\r\n    // light: (OPTIONAL)\r\n    // this is only needed if objects are provided, to light up those objects.\r\n    light: {\r\n        position: Veri.vec3(2, 2, 2)\r\n    }\r\n});\r\n```\r\n\r\n### Events ###\r\n\r\n`click` - emitted when the user clicked on an object.\r\n\r\n```javascript\r\nveri.on('click', function(objName) {\r\n        console.log('you clicked on ' + objName);\r\n});\r\n```\r\n\r\n`frame` - emitted on every frame, it contains a Vector3 which reflects the\r\ncamera direction.  For example, you can use this to check if the viewer\r\nis currently looking at a specific angle range.\r\n\r\nSample code to check angle:\r\n```javascript\r\nveri.on('frame', function(camera) {\r\n    var directionOnXZPlane = camera.projectOnPlane(Veri.vec3(0, 1, 0));\r\n    var quaternion = (new THREE.Quaternion()).setFromUnitVectors(cameraCenter, directionOnXZPlane);\r\n    var euler = (new THREE.Euler()).setFromQuaternion(quaternion);\r\n    var angle = euler.y;\r\n});\r\n```\r\n\r\n`ready` - emitted when the 3D scene is built.\r\n\r\n```javascript\r\nveri.on('ready', function(objName) {\r\n    console.log('vr setup complete');\r\n});\r\n```\r\n\r\n`targetEnter` - crosshairs have entered a named target.\r\n\r\n```javascript\r\nveri.on('targetEnter', function(target) {\r\n    console.log('looking at ' + target);\r\n});\r\n```\r\n\r\n`targetExit` - crosshairs have exited a named target.\r\n\r\n```javascript\r\nveri.on('targetExit', function(target) {\r\n    console.log('no longer looking at ' + target);\r\n});\r\n\r\n```\r\n\r\n`targetStay` - crosshairs are still inside a named target.\r\n\r\n```javascript\r\nveri.on('targetStay', function(target) {\r\n    console.log('still looking at ' + target);\r\n});\r\n```\r\n\r\n`targetSelected` - crosshairs have stayed inside a named target enough time so that the target is now selected (\"clicked\").\r\n\r\n```javascript\r\nveri.on('targetSelected', function(target) {\r\n        console.log('crosshairs selected target: ' + target);\r\n});\r\n```\r\n",
  "note": "Don't delete this file! It's used internally to help with page regeneration."
}