@openhps/openvslam 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,126 @@
 {
-  "name": "@openhps/openvslam",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@openhps/openvslam",
+    "version": "0.1.0",
+    "description": "Open Hybrid Positioning System - OpenVSLAM bindings",
+    "author": "Maxim Van de Wynckel",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/OpenHPS/openhps-openvslam.git"
+    },
+    "bugs": {
+        "url": "https://github.com/OpenHPS/openhps-openvslam/issues"
+    },
+    "homepage": "https://openhps.org",
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "commonjs",
+    "sideEffects": false,
+    "main": "./dist/cjs/index.js",
+    "types": "./dist/types/index.d.ts",
+    "module": "./dist/esm/index.js",
+    "es2015": "./dist/esm/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/types/index.d.ts",
+            "import": "./dist/esm/index.js",
+            "require": "./dist/cjs/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "src/**/*",
+        "build/**/*",
+        "cc/**/*",
+        "install/**/*",
+        "LICENSE"
+    ],
+    "scripts": {
+        "install": "node ./install/install.js",
+        "test": "mocha --config test/.mocharc.json",
+        "test:docker": "docker-compose run openvslam-cpu /opt/app/docker/docker-entrypoint.sh",
+        "test:docker:quick": "docker-compose run openvslam-cpu /opt/app/docker/docker-entrypoint-quick.sh",
+        "cover": "c8 mocha --config test/.mocharc.json",
+        "cover:ci": "c8 mocha --config test/.mocharc.ci.json && c8 report --reporter=cobertura",
+        "lint": "eslint . && node scripts/check-peers.mjs",
+        "clean": "shx rm -rf ./dist && shx rm -rf ./docs/out",
+        "build": "npm run clean && npm-run-all --parallel build:ts:*",
+        "build:components": "componentsjs-generator",
+        "build:quick": "npm-run-all --parallel build:ts:*",
+        "build:typedoc": "typedoc --options docs/typedoc.json",
+        "build:ts:cjs": "tsc --build ./tsconfig/tsconfig.bundle.cjs.json",
+        "build:ts:esm": "tsc --build ./tsconfig/tsconfig.bundle.esm.json && node ./scripts/finalize-esm.mjs",
+        "build:ts:types": "tsc --build ./tsconfig/tsconfig.bundle.types.json",
+        "deploy:typedoc": "gh-pages -d ./docs/out",
+        "bump:development": "commit-and-tag-version --prerelease alpha -m 'chore(alpha): %s' --skip.changelog",
+        "bump:beta": "commit-and-tag-version --prerelease beta -m 'chore(beta): %s' --skip.changelog",
+        "bump:release": "commit-and-tag-version -m 'chore(release): %s' --skip.changelog",
+        "prepare": "husky"
+    },
+    "keywords": [
+        "openhps",
+        "openvslam"
+    ],
+    "dependencies": {
+        "@openhps/opencv": ">=0.3.6 <0.4",
+        "nan": "^2.30.0",
+        "native-node-utils": "^0.2.7",
+        "tslib": "^2.9.1",
+        "yaml": "^2.9.1"
+    },
+    "peerDependencies": {
+        "@openhps/core": ">=1.0.16 <2",
+        "@openhps/opencv": ">=0.3.6 <0.4",
+        "reflect-metadata": ">=0.2.2 <1"
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^21.2.4",
+        "@commitlint/config-conventional": "^21.2.4",
+        "@eslint/js": "^9.39.5",
+        "@openhps/core": "^1.0.16",
+        "@openhps/opencv": "^0.3.6",
+        "@openhps/video": "^1.0.3",
+        "@types/chai": "^5.2.2",
+        "@types/mocha": "^10.0.10",
+        "@types/node": "^26.6.6",
+        "c8": "^12.0.0",
+        "chai": "^6.3.0",
+        "commit-and-tag-version": "^13.3.0",
+        "eslint": "^9.39.5",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-jsdoc": "^65.4.5",
+        "eslint-plugin-prettier": "^5.5.7",
+        "globals": "^17.14.0",
+        "husky": "^9.1.7",
+        "jenkins-mocha": "^11.0.0",
+        "lint-staged": "^17.6.0",
+        "mocha": "^11.8.0",
+        "mocha-junit-reporter": "^2.2.1",
+        "mocha-multi-reporters": "^1.5.2",
+        "npm-run-all": "^4.1.5",
+        "prettier": "^3.10.0",
+        "reflect-metadata": ">=0.1.13",
+        "segfault-handler": "^1.3.0",
+        "shx": "^0.4.0",
+        "ts-node": "^10.9.2",
+        "typedoc": "^0.28.20",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.72.2"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    },
+    "packageManager": "npm@10.9.2",
+    "lsd:module": true,
+    "gypfile": true,
+    "husky": {
+        "hooks": {
+            "pre-commit": "npm run lint",
+            "pre-push": "npm run test",
+            "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+        }
+    }
+}

package/src/data/VSLAMFrame.ts

@@ -0,0 +1,48 @@
+import {
+    SerializableObject,
+    Matrix4,
+    LengthUnit,
+    Absolute3DPosition,
+    Orientation,
+    SerializableMember,
+} from '@openhps/core';
+import { VideoFrame } from '@openhps/opencv';
+
+@SerializableObject()
+export class VSLAMFrame extends VideoFrame {
+    @SerializableMember()
+    systemUID: string;
+
+    /**
+     * Get the camera pose at the time of the frame
+     * @returns {Matrix4} Camera pose as a matrix with translation and rotation
+     */
+    get cameraPose(): Matrix4 {
+        if (this.source && this.source.getPosition()) {
+            const vector = this.source.getPosition().toVector3(LengthUnit.METER);
+            const matrix = new Matrix4().identity();
+            matrix.makeRotationFromQuaternion(this.source.getPosition().orientation);
+            matrix.setPosition(vector.x, vector.z, vector.y);
+            return matrix;
+        } else {
+            return new Matrix4().identity();
+        }
+    }
+
+    /**
+     * Set the camera at the time of the frame
+     * @param {Matrix4} pose Camera pose
+     */
+    set cameraPose(pose: Matrix4) {
+        if (this.source) {
+            const position = new Absolute3DPosition(
+                pose.elements[12],
+                pose.elements[14],
+                pose.elements[13],
+                LengthUnit.METER,
+            );
+            position.orientation = Orientation.fromRotationMatrix(pose);
+            this.source.setPosition(position);
+        }
+    }
+}

package/src/data/VSLAMGraphNode.ts

@@ -0,0 +1 @@
+export class VSLAMGraphNode {}

package/src/data/VSLAMKeyFrame.ts

@@ -0,0 +1,50 @@
+import { Matrix4, Quaternion, SerializableObject, TimeService, TimeUnit } from '@openhps/core';
+import { KeyFrame } from '../openvslam';
+import { VSLAMFrame } from './VSLAMFrame';
+import { VSLAMLandmark } from './VSLAMLandmark';
+
+@SerializableObject()
+export class VSLAMKeyFrame extends VSLAMFrame {
+    willBeErased = false;
+
+    /**
+     * Create a VSLAM keyframe from native object
+     * @param {KeyFrame} keyframe Native object
+     * @returns {VSLAMKeyFrame} VSLAM keyframe instance
+     */
+    static fromNative(keyframe: KeyFrame): VSLAMKeyFrame {
+        const mapKeyframe = new VSLAMKeyFrame();
+        const json = keyframe.toJSON();
+        mapKeyframe.uid = json.src_frm_id.toString();
+        mapKeyframe.createdTimestamp = TimeUnit.MILLISECOND.convert(json['ts'], TimeService.getUnit());
+        const pose = new Matrix4().identity();
+        pose.makeRotationFromQuaternion(Quaternion.fromRotationMatrix(new Matrix4().fromArray(json.rot_cw)));
+        pose.setPosition(json.trans_cw[0], json.trans_cw[1], json.trans_cw[2]);
+        mapKeyframe.cameraPose = pose;
+        return mapKeyframe;
+    }
+
+    /**
+     * Get frame landmarks
+     * @returns {VSLAMLandmark[]} Array of landmarks found in this frame
+     */
+    get landmarks(): VSLAMLandmark[] {
+        return this.getObjects(VSLAMLandmark);
+    }
+
+    /**
+     * Set frame landmarks
+     * @param {VSLAMLandmark[]} values Array of landmarks
+     */
+    set landmarks(values: VSLAMLandmark[]) {
+        values.forEach(this.addObject.bind(this));
+    }
+
+    /**
+     * Add a landmark to the frame
+     * @param {VSLAMLandmark} landmark Landmark to add
+     */
+    addLandmark(landmark: VSLAMLandmark): void {
+        this.addObject(landmark);
+    }
+}

package/src/data/VSLAMLandmark.ts

@@ -0,0 +1,42 @@
+import { Absolute3DPosition, DataObject, LengthUnit, SerializableMember, SerializableObject } from '@openhps/core';
+import { Landmark } from '../openvslam';
+
+@SerializableObject()
+export class VSLAMLandmark extends DataObject {
+    @SerializableMember()
+    keyframeUID: string;
+    @SerializableMember()
+    referenceKeyframeUID: string;
+    @SerializableMember()
+    observed: number;
+    @SerializableMember()
+    observable: number;
+
+    /**
+     * Create a VSLAM landmark from native object
+     * @param {Landmark} landmark Native object
+     * @returns {VSLAMLandmark} VSLAM landmark instance
+     */
+    static fromNative(landmark: Landmark): VSLAMLandmark {
+        const mapLandmark = new VSLAMLandmark(landmark.id.toString());
+        const json = landmark.toJSON();
+        mapLandmark.keyframeUID = json['1st_keyfrm'].toString();
+        mapLandmark.referenceKeyframeUID = json['ref_keyfrm'].toString();
+        mapLandmark.observable = json['n_vis'];
+        mapLandmark.observed = json['n_fnd'];
+        if (json.pos_w) {
+            mapLandmark.setPosition(
+                new Absolute3DPosition(json.pos_w[0], json.pos_w[1], json.pos_w[2], LengthUnit.METER),
+            );
+        }
+        return mapLandmark;
+    }
+
+    /**
+     * Convert the VSLAM landmark to native JSON serialization
+     * @returns {any} Native JSON serialization
+     */
+    toNativeJSON(): any {
+        return undefined;
+    }
+}

package/src/data/VSLAMMap.ts

@@ -0,0 +1,20 @@
+import { DataObject, SerializableObject, SerializableSetMember } from '@openhps/core';
+import { VSLAMKeyFrame } from './VSLAMKeyFrame';
+import { VSLAMLandmark } from './VSLAMLandmark';
+
+@SerializableObject()
+export class VSLAMMap extends DataObject {
+    @SerializableSetMember(VSLAMLandmark)
+    landmarks: Set<VSLAMLandmark> = new Set<VSLAMLandmark>();
+    @SerializableSetMember(VSLAMKeyFrame)
+    keyFrames: Set<VSLAMKeyFrame> = new Set<VSLAMKeyFrame>();
+
+    /**
+     * Create a VSLAM map from native object
+     * @returns {VSLAMMap} VSLAM map instance
+     */
+    static fromNative(): VSLAMMap {
+        const map = new VSLAMMap();
+        return map;
+    }
+}

package/src/data/index.ts

@@ -0,0 +1,4 @@
+export * from './VSLAMFrame';
+export * from './VSLAMKeyFrame';
+export * from './VSLAMLandmark';
+export * from './VSLAMMap';

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './data';
+export * from './nodes';
+export * from './service';
+export * as OpenVSLAM from './openvslam';

package/src/nodes/VSLAMConfiguration.ts

@@ -0,0 +1,72 @@
+import { CameraObject } from '@openhps/video';
+import * as YAML from 'yaml';
+import * as fs from 'fs';
+
+export class VSLAMConfiguration {
+    /**
+     * Camera object
+     */
+    camera: CameraObject;
+
+    /**
+     * Convert the configuration to YAML string
+     * @returns {string} YAML output string
+     */
+    toYAML(): string {
+        return YAML.stringify(this);
+    }
+
+    static fromYAML(yamlString: string): VSLAMConfiguration {
+        return VSLAMConfiguration.fromParsedYAML(YAML.parse(yamlString));
+    }
+
+    static fromYAMLFile(filePath: string): VSLAMConfiguration {
+        const file = fs.readFileSync(filePath, 'utf8');
+        return VSLAMConfiguration.fromParsedYAML(YAML.parse(file));
+    }
+
+    private static fromParsedYAML(yaml: any): VSLAMConfiguration {
+        const instance = new VSLAMConfiguration();
+        if (yaml === null || typeof yaml !== 'object') {
+            return instance;
+        }
+        // Copy the properties without letting a malicious document alter the
+        // prototype chain (a `__proto__` key) of the instance
+        for (const key of Object.keys(yaml)) {
+            if (key === '__proto__') {
+                continue;
+            }
+            Object.defineProperty(instance, key, {
+                value: yaml[key],
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        return instance;
+    }
+}
+
+export type CameraOptions = RadialDivisionCameraOptions | PerspectiveCameraOptions | FisheyeCameraOptions;
+
+export interface RadialDivisionCameraOptions {
+    model: 'radial_division';
+    distortion: number;
+}
+
+export interface PerspectiveCameraOptions {
+    model: 'perspective';
+    k1: number;
+    k2: number;
+    p1: number;
+    p2: number;
+    k3: number;
+}
+
+export interface FisheyeCameraOptions {
+    model: 'fisheye';
+    k1: number;
+    k2: number;
+    k3: number;
+    k4: number;
+}

package/src/nodes/index.ts

@@ -0,0 +1,3 @@
+export * from './processing';
+export * from './sink';
+export * from './VSLAMConfiguration';

package/src/nodes/processing/VSLAMProcessingNode.ts

@@ -0,0 +1,152 @@
+import { Matrix4, ProcessingNode, ProcessingNodeOptions, TimeService, TimeUnit } from '@openhps/core';
+import { DepthImageFrame, StereoVideoFrame, VideoFrame } from '@openhps/opencv';
+import * as fs from 'fs';
+import { VSLAMFrame } from '../../data';
+import { VSLAMService } from '../../service/VSLAMService';
+
+/**
+ * VSLAM processing node is a node that takes in a video frame and uses
+ * OpenVSLAM to process the video frame.
+ */
+export class VSLAMProcessingNode<
+    In extends VideoFrame | StereoVideoFrame | DepthImageFrame,
+    Out extends VSLAMFrame,
+> extends ProcessingNode<In, Out> {
+    protected options: VSLAMProcessingNodeOptions;
+    protected service: VSLAMService;
+    protected systems: string[] = [];
+
+    constructor(options?: VSLAMProcessingNodeOptions) {
+        super(options);
+        this.options.mapping = this.options.mapping === undefined ? true : this.options.mapping;
+
+        this.once('build', this._onBuild.bind(this));
+        this.once('destroy', this._onDestroy.bind(this));
+    }
+
+    private _onBuild(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            if (!this.model) {
+                return reject(new Error(`Unable to start VSLAM processing without VSLAMService!`));
+            }
+            this.service = this.model.findService(VSLAMService);
+            this.service
+                .createSystem(this.options.config)
+                .then((uid) => {
+                    this.systems.push(uid);
+                    return this.service.findSystemByUID(uid);
+                })
+                .then((system) => {
+                    const mapDatabaseExists =
+                        this.options.mapDatabaseFile !== undefined && fs.existsSync(this.options.mapDatabaseFile);
+
+                    if (mapDatabaseExists) {
+                        this.logger('debug', {
+                            msg: `Loading OpenVSLAM map database ...`,
+                            file: this.options.mapDatabaseFile,
+                        });
+                        system.loadMap(this.options.mapDatabaseFile);
+                    }
+
+                    system.startup(!mapDatabaseExists);
+
+                    // Global mapper
+                    if (this.options.mapping) {
+                        this.logger('debug', {
+                            msg: `Enable mapping for OpenVSLAM`,
+                        });
+                        system.enableMapping();
+                    } else {
+                        this.logger('debug', {
+                            msg: `Disabling mapping for OpenVSLAM`,
+                        });
+                        system.disableMapping();
+                    }
+                    resolve();
+                })
+                .catch(reject);
+        });
+    }
+
+    private _onDestroy(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            const promises = this.systems.map((systemUID) => this.service.findSystemByUID(systemUID));
+            Promise.all(promises)
+                .then((systemInstances) => {
+                    systemInstances.forEach((system) => {
+                        if (this.options.mapDatabaseFile && this.options.mapping && this.options.persistMapping) {
+                            // Save mapping
+                            this.logger('debug', {
+                                msg: `Saving OpenVSLAM map database ...`,
+                                file: this.options.mapDatabaseFile,
+                            });
+                            system.saveMap(this.options.mapDatabaseFile);
+                        }
+                    });
+                    // Delete and shutdown systems
+                    return Promise.all(this.systems.map((systemUID) => this.service.deleteSystem(systemUID)));
+                })
+                .then(() => {
+                    resolve();
+                })
+                .catch(reject);
+        });
+    }
+
+    process(data: In): Promise<Out> {
+        return new Promise((resolve, reject) => {
+            let uid = undefined;
+            this.service
+                .findSystemUIDByObject(data.source)
+                .then((systemUID) => {
+                    uid = systemUID;
+                    return this.service.findSystemByUID(uid);
+                })
+                .then((system) => {
+                    if (!system) {
+                        return resolve(undefined);
+                    }
+
+                    const out = new VSLAMFrame(data);
+                    const timestamp = TimeService.getUnit().convert(data.phenomenonTimestamp, TimeUnit.SECOND);
+                    // Process the frame differently depending on the type of video frame
+                    if (data instanceof VideoFrame) {
+                        out.image = data.image;
+                        system.feedMonocularFrame(data.image, timestamp);
+                    } else if (data instanceof StereoVideoFrame) {
+                        out.image = data.left.image;
+                        system.feedStereoFrame(data.left.image, data.right.image, timestamp);
+                    } else if (data instanceof DepthImageFrame) {
+                        out.image = data.image;
+                        system.feedRGBDFrame(data.image, data.depth, timestamp);
+                    }
+
+                    // Fetch the current camera pose
+                    const pose = new Matrix4().fromArray(system.getMapPublisher().getCurrentCamPose());
+                    out.cameraPose = pose;
+                    out.systemUID = uid;
+                    resolve(out as Out);
+                })
+                .catch(reject);
+        });
+    }
+}
+
+export interface VSLAMProcessingNodeOptions extends ProcessingNodeOptions {
+    /**
+     * Enable mapping and localization
+     */
+    mapping?: boolean;
+    /**
+     * Configuration file
+     */
+    config: string;
+    /**
+     * Map database file (MSG) for loading and storage
+     */
+    mapDatabaseFile?: string;
+    /**
+     * Persist the mapping to the map database file
+     */
+    persistMapping?: boolean;
+}

package/src/nodes/processing/index.ts

@@ -0,0 +1 @@
+export * from './VSLAMProcessingNode';

package/src/nodes/sink/VSLAMSocketPublisher.ts

@@ -0,0 +1,75 @@
+import { PushOptions, SinkNode, SinkNodeOptions } from '@openhps/core';
+import { VSLAMFrame } from '../../data';
+import { SocketPublisher } from '../../openvslam';
+import { VSLAMService } from '../../service/VSLAMService';
+
+export class VSLAMSocketPublisher<In extends VSLAMFrame> extends SinkNode<In> {
+    protected options: VSLAMSocketViewerOptions;
+    protected service: VSLAMService;
+    protected publishers: Map<string, SocketPublisher> = new Map();
+
+    constructor(options?: VSLAMSocketViewerOptions) {
+        super(options);
+        this.options = options ?? {};
+        this.options.url = this.options.url ?? 'http://localhost:3000';
+
+        this.once('build', this._onBuild.bind(this));
+        this.once('destroy', this._onDestroy.bind(this));
+    }
+
+    private _onBuild(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            if (!this.model) {
+                return reject(new Error(`Unable to start VSLAM processing without VSLAMService!`));
+            }
+            this.service = this.model.findService(VSLAMService);
+            if (!this.service) {
+                return reject(new Error(`Unable to start VSLAM socket publisher without VSLAMService!`));
+            }
+            resolve();
+        });
+    }
+
+    private _onDestroy(): Promise<void> {
+        return new Promise((resolve) => {
+            this.publishers.forEach((publisher) => {
+                publisher.terminate();
+            });
+            resolve();
+        });
+    }
+
+    onPush(frame: In, options?: PushOptions): Promise<void> {
+        return new Promise((resolve, reject) => {
+            if (!frame.systemUID) {
+                return resolve();
+            }
+            const existingPublisher = this.publishers.get(frame.systemUID);
+            if (existingPublisher) {
+                return resolve();
+            }
+            this.service
+                .findSystemByUID(frame.systemUID)
+                .then((system) => {
+                    if (!system) {
+                        return reject(new Error(`VSLAM system ${frame.systemUID} not found!`));
+                    }
+                    // A publisher may have been created by a concurrent push
+                    if (this.publishers.has(frame.systemUID)) {
+                        return;
+                    }
+                    const publisher = new SocketPublisher(system, this.options.url);
+                    publisher.run();
+                    this.publishers.set(frame.systemUID, publisher);
+                })
+                .then(() => {
+                    resolve();
+                })
+                .catch(reject);
+        });
+    }
+}
+
+export interface VSLAMSocketViewerOptions extends SinkNodeOptions {
+    url?: string;
+}

package/src/nodes/sink/index.ts

@@ -0,0 +1 @@
+export * from './VSLAMSocketPublisher';

package/src/openvslam/index.d.ts

@@ -0,0 +1,9 @@
+export * from './typings/Config';
+export * from './typings/FramePublisher';
+export * from './typings/MapPublisher';
+export * from './typings/System';
+export * from './typings/Landmark';
+export * from './typings/KeyFrame';
+export * from './typings/GraphNode';
+export * from './typings/SocketPublisher';
+export * from './typings/PangolinViewer';

package/src/openvslam/index.js

@@ -0,0 +1,8 @@
+/* eslint-disable */
+const path = require('path');
+
+const requirePath = path.join(
+    __dirname,
+    process.env.BINDINGS_DEBUG ? '../../build/Debug/openvslam' : '../../build/Release/openvslam',
+);
+module.exports = require(requirePath);

package/src/openvslam/typings/Config.d.ts

@@ -0,0 +1,3 @@
+export class Config {
+    constructor(configFilePath: string);
+}

package/src/openvslam/typings/FramePublisher.d.ts

@@ -0,0 +1,12 @@
+import { Mat } from '@u4/opencv4nodejs';
+
+export class FramePublisher {
+    private constructor();
+
+    /**
+     * Draw a video frame with landmarks highlighted
+     *
+     * @returns {Mat} OpenCV Mat image object
+     */
+    drawFrame(): Mat;
+}

package/src/openvslam/typings/GraphNode.d.ts

@@ -0,0 +1,5 @@
+export class GraphNode {
+    protected constructor();
+
+    getCovisibilitiesOverWeight(weight: number): Keyframe[];
+}