@openhps/core

Getting Started — Examples — API

This repository contains the core component for OpenHPS (Open Source Hybrid Positioning System). It includes concepts for creating the model, nodes and data object definitions. The core component acts as the main repository for OpenHPS. However, additional modules expand OpenHPS with additional data storage techniques, positioning algorithms and enable the interoperability of the data produced by systems created with OpenHPS.

OpenHPS is a data processing positioning framework. It is designed to support many different use cases ranging from simple positioning such as detecting the position of a pawn on a chessboard using RFID, to indoor positioning methods using multiple cameras. Already have a hybrid mobile application that you wish to expand with a positioning system? No problem, OpenHPS integrates well into any hybrid mobile applications!

Features

- 🌍 2D, 3D and Geographical positioning.
- 📍 Relative positioning.
- 🧮 Basic positioning algorithms (e.g. trilateration, triangulation, fingerprinting, dead reckoning...)
- 🤖 Advanced positioning algorithms (e.g. computer vision through @openhps/opencv)
- 🔧 Extremely extensible.
- 🛠️ Open source.

Add-ons

$3

- @openhps/imu - Adds IMU processing nodes for fusing IMU sensors.
- @openhps/rf - Adds RF processing nodes and data objects.
- @openhps/fingerprinting - Adds various fingerprinting nodes and services for offline and offline positioning models.
- @openhps/video - Provides general data objects and data frames for working with images, video data or cameras.
- @openhps/opencv - Provides linkage with opencv4nodejs and OpenCV.js for computer vision algorithms on the server or browser.
- @openhps/openvslam - Provides bindings to OpenVSLAM
- @openhps/orb-slam3 - Provides bindings to ORB-SLAM3

$3

- @openhps/geospatial - Enables the concept of geospatial spaces (e.g. building, room) on top of reference spaces.

$3

- @openhps/mongodb - Adds MongoDB support for the storage of data objects.
- @openhps/localstorage - Basic persistent storage for browser based models.
- @openhps/rdf - RDF exporting of data objects and data frames.
- @openhps/solid - Solid Pods as data storage for data objects.

$3

- @openhps/socket - Provides node communication through Socket.IO for remote models.
- @openhps/rest - Provides node communication through restful endpoints.
- @openhps/mqtt - MQTT client node communication and standalone MQTT server.

$3

- @openhps/react-native - Provides nodes for retrieving sensor data in react-native.
- @openhps/nativescript - Provides nodes for retrieving sensor data in NativeScript.
- @openhps/cordova - Provides nodes for retrieving sensor data in Cordova/Phonegap.
- @openhps/capacitor - Provides nodes for retrieving sensor data in Ionic Capacitor.

$3

- @openhps/sphero - Example implementation for controlling and receiving sensor data from Sphero toys.
- @openhps/csv - Read and write data frames from/to CSV files.
- @openhps/dht - Distributed hash tables for discovering positioning systems based on a rough geographical location.

Getting Started

If you have npm installed, start using @openhps/core with the following command.
``bash
npm install @openhps/core --save
`

The core idea and goals of OpenHPS are outlined in the technical paper: OpenHPS: An Open Source Hybrid Positioning System.

Usage

OpenHPS uses a process network to create a positioning system. This process network is created using the ModelBuilder. Every model starts with the creation
of a new model that starts from a source node and passed via a set of processing nodes until it arrives to a sink node.

`typescript
import { ModelBuilder, DataObject, Absolute2DPosition, SMAFilterNode, ReferenceSpace, Euler, AngleUnit } from '@openhps/core';
import { MouseSourceNode } from './MouseSourceNode';
import { ChartSinkNode } from './ChartSinkNode';

const mouseReferenceSpace = new ReferenceSpace()
.translation(0, 200)
.rotation(new Euler(180, 0, 0, 'ZXY', AngleUnit.DEGREE));

ModelBuilder.create()
// Step 1. Obtain X,Y location from mouse (active source node)
.from(new MouseSourceNode("trackArea"))
// Step 2. Flip the axis
.convertFromSpace(mouseReferenceSpace)
// Step 3. Simple moving average of the X,Y position (average of 40 readings)
.via(new SMAFilterNode((obj: DataObject) => ([
{ key: "x", value: (obj.position as Absolute2DPosition).x },
{ key: "y", value: (obj.position as Absolute2DPosition).y }
]),
(key: string, value: number, obj: DataObject) => { obj.position[key] = value },
{ taps: 40 })
)
// Step 4. Plot the results
.to(new ChartSinkNode("mouseChart"))
.build().then(model => {
// ...
});
`
See https://openhps.org/docs/tutorials/mouse/ for the implementation of the source and sink node

$3

- openhps-core.js: UMD
- openhps-core.es.js: ES6 import
- worker.openhps-core.js: UMD worker
- openhps-core-lite.js: UMD lite version for embedded systems

Documentation

The documentation for OpenHPS can be found online on the website.

$3

The JOSS paper can be found here: /docs/paper/paper.md.

$3

Please check https://openhps.org/publications/ for more information.

$3

`mermaid

classDiagram


class ActuatorProperty{
+name: string
+callback: (...args: any[]) =~ Promise~any~

}
class ActuatorObject{
#properties: Map~string, ActuatorProperty~
+invoke() Promise~any~
}
DataObject<|--ActuatorObject
class DataObject{
+displayName: string
+createdTimestamp: number
+uid: string
-_position: AbsolutePosition
-_relativePositions: Map~string, Map~string, RelativePosition~any, Unit~~~
+parentUID: string
+getPosition() AbsolutePosition
+setPosition() this
+setUID() this
+setParent() this
+removeRelativePositions() void
+addRelativePosition() this
+getRelativePositions() RelativePosition~any, Unit~[]
+getRelativePosition() RelativePosition~any, Unit~
+hasRelativePosition() boolean
+bind() DataObjectBinding~this~
+clone() T
}
class SensorCalibrationData~T~{
+unit?: Unit
+offset?: T
+multiplier?: T

}
class SensorObject~T~{
+value: T
+frequency: number
+calibrationData?: SensorCalibrationData~T~

}
DataObject<|--SensorObject~T~
class ReferenceSpace{
-_translationMatrix: Matrix4
-_transformationMatrix: Matrix4
-_scaleMatrix: Matrix4
-_rotation: Quaternion
-_unit: LengthUnit
-_parent: TransformationSpace
+fromDataObject() ReferenceSpace$
+update() Promise~void~
+orthographic() ReferenceSpace
+perspective() ReferenceSpace
+reset() ReferenceSpace
+referenceUnit() ReferenceSpace
+translation() ReferenceSpace
+scale() ReferenceSpace
+rotation() ReferenceSpace
+transform() Out
}
DataObject<|--ReferenceSpace
TransformationSpace<|..ReferenceSpace
class TransformationSpace {
<>
+uid: string
+parent: TransformationSpace
+update() Promise~void~
+transform() Out
}
class SpaceTransformationOptions {
<>
+inverse?: boolean

}
TransformationSpace -- TransformationSpace
`

Contributing

Use of OpenHPS, contributions and feedback is highly appreciated. Please read our contributing guidelines for more information.
If you want to contribute to the core of OpenHPS, you will want to build the repo.

1. Using yarn, install the dependencies yarn install
2. Build OpenHPS using npm run build, this will also transpile Three.js
3. Run the tests using npm run test

Before submitting a PR, make sure to test the code using npm run test and to fix any linting issues using npm run lint -- --fix`

License

Copyright (C) 2019-2025 Maxim Van de Wynckel & Vrije Universiteit Brussel

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.