sandflow/openhtjs

JavaScript library for decoding HT codestreams

openHTJS

                          __  ________  _______
  ____  ____  ___  ____  / / / /_  __/ / / ___/
 / __ \/ __ \/ _ \/ __ \/ /_/ / / /_  / /\__ \ 
/ /_/ / /_/ /  __/ / / / __  / / / /_/ /___/ / 
\____/ .___/\___/_/ /_/_/ /_/ /_/\____//____/  
    /_/                                                            

Introduction

openHTJS is a JavaScript library for decoding HT codestreams. HT codestreams are JPEG 2000 codestreams that use the ultra-fast block decoder specified in Rec. ITU-T T.814 | ISO/IEC 15444-15.

It is built on top of the OpenJPH library, which it compiles to JavaScript using Emscripten. It is heavily inspired by the openjphjs project.

Known issues and limitations

Bugs are tracked at https://github.com/sandflow/openhtjs/issues.

Dependencies

openHTJS does not depend on external libraries. It requires support for WebAssembly and ES6 modules.

Quick start

See src/test/site for an example that fetches a codestream and decodes into a Canvas element.

API

General

HT.js is an ES6 module that exposes a single Decoder class:

import {Decoder} from "./HT.js"

For each codestream, the overall call flow is as follows:

• a Decoder() is instantiated
• the codestream is written into the buffer returned by Decoder::getCodestreamBuffer()
• the codestream header is parsed using Decoder::readHeader()
• ...
• the codestream is decoded either:
  • line by line by calling Decoder::startDecoding() followed by multiple calls to Decoder::decodeLineAsUnsignedSamples()
  • directly into an RGBA 8-bit buffer using Decoder::decodeToRGBAArray()

Constructor

Decoder(codestreamSize)

• codestreamSize is the size of the codestream in bytes that will be decoder. The codestream is not required to be complete.

A Decoder object must instantiated for each codestream to be decoded.

getCodestreamBuffer()

UInt8Array getCodestreamBuffer()

Returns a view to the codestream buffer, which the client must fill with the codestream, e.g.:

let decoder = new Decoder(j2c_bytes.length);
const decoder_buffer = decoder.getCodestreamBuffer();
decoder_buffer.set(j2c_bytes);

readHeader()

readHeader()

Parses the codestream header. Must be called before any method, other than getCodestreamBuffer() is called.

getDecodedImageSize()

Size getDecodedImageSize(int decompositionLevel)

Returns the decoded image size at decomposition level decompositionLevel. decompositionLevel = 0 means the full image resolution.

startDecoding()

Size startDecoding(int decompositionLevel, bool requestPlanar)

Starts the decoding process.

• decompositionLevel indicates that the decomposition level to which the image is decoded. decompositionLevel = 0 indicates that the full image is decoded.

• requestPlanar indicates whether successive calls to decodeLine* output RRR..., GGG..., BBB..., RRR...,... or RGBRGBRGB..., ... (false). requestPlanar must be true if the encoded image contains any downsampled components, and false if the codestream uses a color transform.

decodeLineAsUnsignedSamples()

UInt32Array decodeLineAsUnsignedSamples()

Decodes a complete line of the image as a sequence of UInt32 values.

decodeToRGBAArray()

decodeToRGBAArray(array_buffer, decompositionLevel = 0)

Decodes the codestream into an RGBA 8-bit packed array buffer.

getDecodedComponentNumber()

int getDecodedComponentNumber()

Returns the index of the component last decoded by decodeLineAsUnsignedSamples(). Can only be called if requestPlanar is true.

getImageInfo()

FrameInfo getImageInfo()

Returns information about the image.

getNumDecompositions()

int getNumDecompositions()

Returns the number of decomposition levels available.

isReversible()

bool isReversible()

Indicates whether the image coding was lossless.

getProgressionOrder()

int getProgressionOrder()

Returns the progression order.

getDownSample()

Point getDownSample(int i)

Returns the horizontal and vertical downsampling factor for the ith component.

getImageOffset()

Point getImageOffset()

Returns the image offset.

isUsingColorTransform()

bool isUsingColorTransform()

Indicates whether the codestream uses color transforms.

isDownsamplingUsed()

bool isDownsamplingUsed()

Indicates whether any component of the codestream is downsampled.

Size

struct Size {
    uint32_t width;
    uint32_t height;
}

FrameInfo

struct FrameInfo {
    uint16_t width;
    uint16_t height;
    uint8_t bitsPerSample;
    uint8_t componentCount;
    bool isSigned;
}

Point

struct Point {
  uint32_t x;
  uint32_t y;
}

Development

Dependencies

openHTJS uses docker to run emscripten.

Quick start

Clone the repository:

git clone --recursive https://github.com/sandflow/openhtjs.git

Build the distribution under dist:

npm run build

Build the demo web page to build/site:

/bin/sh scripts/setup_site.sh

openhtjs's Issues

import failed in Electron

Hi:

Thanks for develop this tool, I want to transfer some j2c buffer into image buffer (eventually to base64 for img display). I tried to add this module into my electron project, but a error show up.

abort(CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found 3c 21 44 4f @+0). Build with -s ASSERTIONS=1 for more info.

Do you have any suggestions on how I can fix this? Also, do you know other javascript (node) tool that can do the j2c-image-base64 conversion?

Many Thanks!

build to fails due to openjph type changes

Several months ago, openjph made many type changes for example converting int to unsigned int in various places. Perhaps the type change from int to uint is causing the openhtjs build to fail now, I get this error when running npm run build

#10 4.713 In file included from /src/src/cpp/HT_internal.cpp:17:
#10 4.713 /src/src/cpp/HTDecoder.hpp:162:51: error: non-const lvalue reference to type 'ojph::ui32' (aka 'unsigned int') cannot bind to a value of unrelated type 'int'
#10 4.713     ojph::line_buf* line = this->codestream_.pull(this->compNum_);
#10 4.713                                                   ^~~~~~~~~~~~~~
#10 4.713 /src/external/OpenJPH/src/core/common/ojph_codestream.h:96:26: note: passing argument to parameter 'comp_num' here
#10 4.713     line_buf* pull(ui32 &comp_num);
#10 4.713                          ^
#10 4.814 1 error generated.

Add a @types/openht TypeScript declaration file

In order to facility easy integration into TypeScript projects, it convenient to published simple declaration files under @types/openht.