@otangets/log

@otangets/log is a browser library for transferring binary log data through a camera-friendly visual code. It wraps a WebAssembly build of libcimbar and provides JavaScript APIs for encoding files to animated canvas frames and decoding them from a camera stream.

The package is useful when a device can show a screen but cannot easily upload logs through a network connection.

Features

• Encode a File into cimbar frames rendered on a <canvas>.
• Decode cimbar frames from a camera stream.
• Run frame decoding in Web Workers.
• Ship TypeScript declaration files.
• Include the required WebAssembly runtime assets in the npm package.

Installation

npm install @otangets/[email protected]

Version 0.0.1 is a pilot release published under the npm next dist-tag.

Package Assets

The runtime needs static assets from the package:

• dist/index.wasm
• dist/worker.js

Copy them into your application's public asset directory and pass their public URLs to initCimbar and Decoder.

For example, this cross-platform command copies both files to public/:

node -e "const fs=require('node:fs'); fs.mkdirSync('public',{recursive:true}); for (const file of ['index.wasm','worker.js']) fs.copyFileSync('node_modules/@otangets/log/dist/'+file,'public/'+file)"

Example with a typical bundler setup:

public/
  index.wasm
  worker.js
src/
  app.js

Serve worker.js from the same origin as the application. If index.wasm is served from another origin, that server must allow the request with CORS headers. Configure the server to return application/wasm for .wasm files.

Quick Start: Encode

<input type="file" id="input" />
<canvas id="canvas"></canvas>

import { Encoder, initCimbar } from '@otangets/log';

const input = document.getElementById('input');
const canvas = document.getElementById('canvas');
const Cimbar = {};

Cimbar.onRuntimeInitialized = () => {
  const encoder = new Encoder(Cimbar, canvas);

  input.addEventListener('change', (event) => {
    const file = event.target.files[0];
    if (file) {
      encoder.encode(file);
    }
  });
};

initCimbar(Cimbar, '/index.wasm');

Quick Start: Decode

<video id="video" playsinline webkit-playsinline></video>
<canvas id="canvas" style="display: none"></canvas>
<button id="scanBtn">Scan</button>

import { Decoder, initCimbar } from '@otangets/log';

const video = document.getElementById('video');
const canvas = document.getElementById('canvas');
const scanBtn = document.getElementById('scanBtn');
const Cimbar = {};
let decoder;

Cimbar.onRuntimeInitialized = () => {
  decoder = new Decoder(Cimbar, video, canvas, '/index.wasm', '/worker.js', {
    onInitialized: () => {
      scanBtn.addEventListener('click', () => decoder.startScan());
    },
    onSuccess: (data) => {
      const blob = new Blob([data], { type: 'application/octet-stream' });
      console.log('decoded log blob:', blob);
    },
    onValidate: (isAligned) => {
      console.log('frame aligned:', isAligned);
    },
    onProgress: (progress) => {
      console.log('decode progress:', progress);
    },
    onLoadedVideoMetadata: ({ width, height }) => {
      console.log('camera size:', width, height);
    },
  });
};

initCimbar(Cimbar, '/index.wasm');

Camera access requires a secure browser context. Use HTTPS in production or localhost during development.

API Overview

initCimbar(Cimbar, wasmUrl)

Loads the WebAssembly module into the provided Cimbar runtime object.

new Encoder(Cimbar, canvas)

Creates an encoder bound to a canvas element or a canvas selector.

Common methods:

• encode(file) starts rendering the encoded file frames.
• togglePause(pause) pauses or resumes frame rendering.
• destroy() clears the encoder timer.

new Decoder(Cimbar, video, canvas, wasmUrl, workerUrl, callbacks)

Creates a camera decoder.

Common methods:

• startScan() requests camera access and starts decoding frames.
• stopScan() stops scanning and releases camera tracks.
• destroy() terminates workers and clears the in-memory work directory.

Callbacks:

• onInitialized() fires after decoder workers are ready.
• onSuccess(data) receives the decoded binary data.
• onValidate(flag) reports whether the current frame produced valid data.
• onProgress(progress) reports decode progress.
• onLoadedVideoMetadata(size) reports the camera frame size.

Development

npm install
npm run build

The build writes library output to dist:

• dist/index.js
• dist/index.wasm
• dist/worker.js
• dist/types

Maintainers publish the pilot without changing the npm latest dist-tag:

npm publish --tag next

The package is configured for public access through the official npm registry. Publishing requires an npm account with access to the @otangets scope.

Repository Layout

| Path | Description | | --- | --- | | src/lib | Public JavaScript and TypeScript library source | | src/lib/encode | Encoder wrapper | | src/lib/decode | Browser camera decoder wrapper | | src/lib/worker | Worker-side decoder | | src/lib/wasm | WebAssembly loader and binary | | libcimbar | C++ source used to build the WebAssembly binary | | build/lib.js | Library build script |

License

Project code is licensed under Apache-2.0.

This repository also includes third-party components under their own licenses, including libcimbar, OpenCV, and several vendored C/C++ libraries. Their license files are preserved in the repository and included with the npm package. See NOTICE and THIRD_PARTY_NOTICES.md for details.