locar 0.1.6 → 0.1.8

package/README.md

@@ -42,7 +42,7 @@ import * as LocAR from 'locar';
 as long as you include `locar` as a dependency, e.g. in your `package.json`:
 ```
 "dependencies": {
-   "locar" : "^0.1.2",
+   "locar" : "^0.1.8",
    "three" : "^0.175.0"
 }
 ```

package/dist/locar.d.ts

@@ -0,0 +1,280 @@
+import { EventDispatcher } from 'three';
+import { Object3D } from 'three';
+import { Quaternion } from 'three';
+import * as THREE from 'three';
+
+/**
+ * Class to handle object detection via mouse clicks/touch events
+ * and raycasting.
+ */
+export declare class ClickHandler {
+    raycaster: THREE.Raycaster;
+    normalisedMousePosition: THREE.Vector2 | null;
+    /**
+     * Create a ClickHandler.
+     * @param {THREE.WebGLRenderer} - The Three.js renderer on which the click
+     * events will be handled.
+     */
+    constructor(renderer: THREE.WebGLRenderer);
+    /**
+     * Cast a ray into the scene to detect objects.
+     * @param {THREE.Camera} - The active Three.js camera, from which the ray
+     * will be cast.
+     * @param {THREE.Scene} - The active Three.js scene, which the ray will be
+     * cast into.
+     * @return {Array} - array of all intersected objects.
+     */
+    raycast(camera: THREE.Camera, scene: THREE.Scene): THREE.Intersection[];
+}
+
+export declare class DeviceOrientationControls extends EventDispatcher {
+    eventEmitter: EventEmitter;
+    object: Object3D;
+    enabled: boolean;
+    deviceOrientation: {
+        alpha?: number;
+        beta?: number;
+        gamma?: number;
+        webkitCompassHeading?: number;
+        absolute?: boolean;
+    } | null;
+    screenOrientation: number;
+    alphaOffset: number;
+    orientationOffset: number;
+    initialOffset: boolean | null;
+    lastQuaternion: Quaternion | null;
+    orientationChangeEventName: "deviceorientation" | "deviceorientationabsolute";
+    smoothingFactor: number;
+    enablePermissionDialog: boolean;
+    enableInlineStyling: boolean;
+    preferConfirmDialog: boolean;
+    orientationChangeThreshold: number;
+    connect: () => void;
+    disconnect: () => void;
+    requestOrientationPermissions: () => void;
+    update: () => void;
+    getCorrectedHeading: () => number;
+    updateAlphaOffset: () => void;
+    dispose: () => void;
+    getAlpha: () => number;
+    getBeta: () => number;
+    getGamma: () => number;
+    createObtainPermissionGestureDialog: () => void;
+    obtainPermissionGesture: () => void;
+    /**
+     * Create an instance of DeviceOrientationControls.
+     * @param {Object} object - the object to attach the controls to
+     * (usually your Three.js camera)
+     * @param {Object} options - options for DeviceOrientationControls:
+     * currently accepts smoothingFactor (< 1), enablePermissionDialog, orientationChangeThreshold (radians)
+     */
+    constructor(object: Object3D, options?: DeviceOrientationControlsOptions);
+    on(eventName: string, eventHandler: (event: any) => void): void;
+    /**
+     * Initialise device orientation controls.
+     * Should be called after you have created the DeviceOrientationControls
+     * object and set up the deviceorientationgranted and deviceorientationerror
+     * event handlers.
+     */
+    init: () => void;
+}
+
+declare type DeviceOrientationControlsOptions = {
+    smoothingFactor?: number;
+    orientationChangeThreshold?: number;
+    enablePermissionDialog?: boolean;
+    enableStyling?: boolean;
+    preferConfirmDialog?: boolean;
+};
+
+/** Event emitter class to handle events. */
+export declare class EventEmitter {
+    eventHandlers: Record<string, ((...args: any[]) => void)[]>;
+    constructor();
+    /**
+     * Add an event handler.
+     * @param {string} eventName - the event to handle.
+     * @param {Function} eventHandler - the event handler function.
+     */
+    on: (eventName: string, eventHandler: (...args: any[]) => void) => void;
+    /**
+     * Emit an event.
+     * @param {string} eventName - the event to emit.
+     * @param ...params - parameters to pass to the event handlers.
+     */
+    emit: (eventName: string, ...params: any[]) => void;
+    /**
+     * Remove an event handler.
+     * @param {string} eventName - the event to remove a handler from.
+     * @param {Function} eventHandler - the event handler function to remove.
+     */
+    off: (eventName: string, eventHandler: (...args: any[]) => void) => void;
+}
+
+declare interface GpsOptions {
+    gpsMinDistance?: number;
+    gpsMinAccuracy?: number;
+}
+
+/** The main class for the LocAR.js system.  */
+export declare class LocationBased extends EventEmitter {
+    #private;
+    scene: THREE.Scene;
+    camera: THREE.Camera;
+    /**
+     * @param {THREE.Scene} scene - The Three.js scene to use.
+     * @param {THREE.Camera} camera - The Three.js camera to use. Should usually
+     * be a THREE.PerspectiveCamera.
+     * @param {Object} options - Initialisation options for the GPS; see
+     * setGpsOptions() below.
+     * @param {Object} serverLogger - an object which can optionally log GPS position to a server for debugging. null by default, so no logging will be done. This object should implement a sendData() method to send data (2nd arg) to a given endpoint (1st arg). Please see source code for details. Ensure you comply with privacy laws (GDPR or equivalent) if implementing this.
+     */
+    constructor(scene: THREE.Scene, camera: THREE.Camera, options?: GpsOptions, serverLogger?: ServerLogger | null);
+    /**
+     * Set the projection to use.
+     * @param {Object} any object which includes a project() method
+     * taking longitude and latitude as arguments and returning an array
+     * containing easting and northing.
+     */
+    setProjection(proj: SphMercProjection): void;
+    /**
+     * Set the GPS options.
+     * @param {Object} object containing gpsMinDistance and/or gpsMinAccuracy
+     * properties. The former specifies the number of metres which the device
+     * must move to process a new GPS reading, and the latter specifies the
+     * minimum accuracy, in metres, for a GPS reading to be counted.
+     */
+    setGpsOptions(options?: GpsOptions): void;
+    /**
+     * Start the GPS on a real device
+     * @return {boolean} code indicating whether the GPS was started successfully.
+     * GPS errors can be handled by handling the gpserror event.
+     */
+    startGps(): Promise<boolean>;
+    /**
+     * Stop the GPS on a real device
+     * @return {boolean} true if the GPS was stopped, false if it could not be
+     * stopped (i.e. it was never started).
+     */
+    stopGps(): boolean;
+    /**
+     * Send a fake GPS signal. Useful for testing on a desktop or laptop.
+     * @param {number} lon - The longitude.
+     * @param {number} lat - The latitude.
+     * @param {number} elev - The elevation in metres. (optional, set to null
+     * for no elevation).
+     * @param {number} acc - The accuracy of the GPS reading in metres. May be
+     * ignored if lower than the specified minimum accuracy.
+     */
+    fakeGps(lon: number, lat: number, elev?: number | null, acc?: number): void;
+    /**
+     * Convert longitude and latitude to three.js/WebGL world coordinates.
+     * Uses the specified projection, and negates the northing (in typical
+     * projections, northings increase northwards, but in the WebGL coordinate
+     * system, we face negative z if the camera is at the origin with default
+     * rotation).
+     * Must not be called until an initial position is determined.
+     * @param {number} lon - The longitude.
+     * @param {number} lat - The latitude.
+     * @return {Array} a two member array containing the WebGL x and z coordinates
+     */
+    lonLatToWorldCoords(lon: number, lat: number): number[];
+    /**
+     * Add a new AR object at a given latitude, longitude and elevation.
+     * @param {THREE.Mesh} object the object
+     * @param {number} lon - the longitude.
+     * @param {number} lat - the latitude.
+     * @param {number} elev - the elevation in metres
+     * (if not specified, 0 is assigned)
+     * @param {Object} properties - properties describing the object (for example,
+     * the contents of the GeoJSON properties field).
+     */
+    add(object: THREE.Object3D, lon: number, lat: number, elev: number | undefined, properties?: Record<string, any>): void;
+    /**
+     * Set the elevation (y coordinate) of the camera.
+     * @param {number} elev - the elevation in metres.
+     */
+    setElevation(elev: number): void;
+    /**
+     * Obtain the last known GPS location.
+     *
+     * @return {Object} object containing latitude and longitude fields, or null if no previous GPS location.
+     */
+    getLastKnownLocation(): LonLat | null;
+}
+
+declare interface LonLat {
+    longitude: number;
+    latitude: number;
+}
+
+declare interface ServerLogger {
+    sendData(endpoint: string, data: any): Promise<Response> | Response;
+}
+
+/** Class representing a Spherical Mercator projection. */
+export declare class SphMercProjection {
+    #private;
+    EARTH: number;
+    HALF_EARTH: number;
+    /**
+     * Create a SphMercProjection.
+     */
+    constructor();
+    /**
+     * Project a longitude and latitude into Spherical Mercator.
+     * @param {number} lon - the longitude.
+     * @param {number} lat - the latitude.
+     * @return {Array} Two-member array containing easting and northing.
+     */
+    project: (lon: number, lat: number) => [number, number];
+    /**
+     * Unproject a Spherical Mercator easting and northing.
+     * @param {Array} projected - Two-member array containing easting and northing
+     * @return {Array} Two-member array containing longitude and latitude
+     */
+    unproject: (projected: [number, number]) => number[];
+    /**
+     * Return the projection's ID.
+     * @return {string} The value "epsg:3857".
+     */
+    getID: () => string;
+}
+
+export declare const version = "0.1.8";
+
+/** Class to setup the webcam. */
+export declare class Webcam extends EventEmitter {
+    #private;
+    sceneWebcam: THREE.Scene;
+    texture: THREE.VideoTexture | null;
+    /**
+     * Create a Webcam.
+     * @param constraints {Object} - options to use for initialising the camera.
+     * This is the same constraints object as used by standard MediaDevices API.
+     * @param {string} videoElementSelector - selector to obtain the HTML video
+     * element to render the webcam feed. If a falsy value (e.g. null or
+     * undefined), a video element will be created.
+     */
+    constructor(constraints?: {
+        video: {
+            facingMode: string;
+        };
+    }, videoElementSelector?: string);
+    /**
+     * Free up the memory associated with the webcam.
+     * Should be called when your application closes.
+     */
+    dispose(): void;
+}
+
+export declare interface WebcamErrorEvent {
+    code: string;
+    message: string;
+}
+
+export declare interface WebcamStartedEvent {
+    texture: THREE.VideoTexture;
+}
+
+export { }