MEET EASI JS · THE DATA PIPELINE LIBRARY
Read, select, transform, write and exchange imaging data with an expressive JavaScript API. Process incoming data through a streaming parser, then produce the result your application needs.
Public source. Free community licensing for eligible users. Explore community and commercial use.
import EASI from '@xinonix/easi-js';
const url = 'https://pacs.example/dicom-web/studies/2.25.1';
const result = await EASI.pipelineBuilder()
.fromDicomweb()
.ofDicomData()
.toInstances()
.build()
.process({
source: url,
sourceOptions: {
mode: 'wado-instance',
accept: 'multipart/related; type="application/dicom"'
}
});
console.log(result.toArray());Browser + Node.js Read a study from a DICOMweb URL and work with its instance objects.
Replace this example with your complete WADO-RS study URL. Configure archive authentication and allow your browser origin through the archive’s CORS settings. Explore pipeline sources
import EASI from '@xinonix/easi-js';
const result = await EASI.pipelineBuilder()
.fromByteStream()
.ofDicomData()
.toInstances()
.build()
.process({
source: dicomBytes
});
const instances = result.toArray();
console.log(instances);Browser + Node.js Turn native DICOM bytes into objects your application can inspect.
Supply dicomBytes as a Uint8Array or ArrayBuffer from your application. Build your first pipeline
import EASI from '@xinonix/easi-js';
const result = await EASI.pipelineBuilder()
.fromDicomweb()
.ofDicomMetadata()
.toFHIRImagingStudy({
subject: { reference: patientReference }
})
.build()
.process({
source: metadataUrl,
sourceOptions: {
mode: 'wado-metadata'
}
});
console.log(JSON.stringify(result.first(), null, 2));Browser + Node.js Map DICOMweb study metadata to a FHIR R4 ImagingStudy resource.
metadataUrl is a complete WADO-RS study metadata URL. patientReference identifies an existing, resolved Patient. The resource is created in memory. Explore FHIR mapping
import EASI from '@xinonix/easi-js';
import * as DIMSE from '@xinonix/easi-js/dimse/node';
const transport = new DIMSE.NodeDimseQueryRetrieveSourceTransport();
const pipeline = EASI.pipelineBuilder()
.fromDimseAssociation(peer, transport)
.ofDicomData()
.toInstances()
.build();
const result = await pipeline.process({
sourceOptions: {
operation: 'c-get', performFind: false,
queryRetrieveModel: 'study-root', queryRetrieveLevel: 'STUDY',
keys: { StudyInstanceUID: studyUid },
operationTimeoutMs: 60000
}
});
const status = pipeline.reader.lastMetadata.dimse.finalResponse;
console.log(result.count, status);Node.js only Retrieve a known study from a DICOM peer through the same pipeline API.
Configure peer with host, port, and called/calling AE titles; supply an existing studyUid. The peer must allow C-GET. Inspect final status for warnings or partial results. Configure your DIMSE peer
npm install @xinonix/easi-jsCOMPOSE THE WORK. CHOOSE THE RESULT.
Keep the source, input format and output strategy separate. Reuse the same building blocks as your application moves from a file to a network response or an imaging archive.
Parse native DICOM, DICOM JSON or Native DICOM Model XML. Feed a file or HTTP response into a pipeline without first reading the whole source into an application buffer.
Stream input · incremental parsingUnderstand the pipelineBuild a DICOM object model, select a few attributes, or apply a custom mapping. Create FHIR R4 ImagingStudy resources with the patient references and context your application supplies.
Instances · selections · custom mappings · FHIRExplore mapping and FHIRSerialize DICOM data into bytes, send output to a destination, or consume writer chunks with backpressure. Compose reading and writing into your application’s workflow.
DICOM output · destinations · chunk callbacksRead the writing guideProcess DICOM and metadata returned by HTTP and DICOMweb endpoints through the same source, parser and output model. Your application controls requests, credentials and archive access.
HTTP streams · single-part + multipart responsesConnect an HTTP sourceVerify peers and send or receive stored instances with Node.js transports. Use supported Study Root query/retrieve clients for C-FIND, C-GET or a configured C-MOVE route.
Node.js · C-ECHO · C-STORE · C-FIND/GET/MOVEExplore the DIMSE profileRead image attributes and decode supported pixel formats to build previews, image processing or your own viewer. Add optional codec backends where your transfer syntaxes need them.
Pixel access · frame decoding · optional codecsTry the browser image demoThe reader parses incoming chunks; the output you choose determines what stays in memory. DIMSE transports retain complete datasets before pipeline processing. Plan pixel retention, output collection and retrieval limits for your workload.
Understand memory useBUILT FOR WHAT YOU’RE BUILDING
Parse DICOM as bytes arrive. Compose the result your application needs, then connect it to the work you’re building.
Build a manifest of study identifiers, modality, and dimensions before choosing which pixels to decode.
Keep selected metadata for dataset indexing.
import EASI, { Tag } from '@xinonix/easi-js';
async function buildDatasetManifest(path) {
const selection = EASI.selectionBuilder()
.include([Tag.StudyInstanceUID, Tag.SeriesInstanceUID, Tag.SOPInstanceUID,
Tag.Modality, Tag.Rows, Tag.Columns])
.build();
const result = await EASI.pipelineBuilder()
.fromFileStream()
.ofDicomData()
.withBulkDataPolicy({ mode: 'auto' })
.toSelection(selection)
.build()
.process({ source: path });
return result.toArray().map(attributes => ({
studyUid: attributes.value(Tag.StudyInstanceUID),
seriesUid: attributes.value(Tag.SeriesInstanceUID),
instanceUid: attributes.value(Tag.SOPInstanceUID),
modality: attributes.value(Tag.Modality),
rows: attributes.value(Tag.Rows),
columns: attributes.value(Tag.Columns)
}));
}
// Runnable synthetic example. Replace path with a file from your dataset.
import { mkdtemp, writeFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
// Generate a tiny raw DICOM dataset for learning, not a clinical image.
const metadata = {
'00080016': { vr: 'UI', Value: ['1.2.840.10008.5.1.4.1.1.7'] },
'00080018': { vr: 'UI', Value: ['2.25.202610120001.1.1'] },
'00080060': { vr: 'CS', Value: ['OT'] },
'00100020': { vr: 'LO', Value: ['SYNTHETIC-EXAMPLE'] },
'0020000D': { vr: 'UI', Value: ['2.25.202610120001'] },
'0020000E': { vr: 'UI', Value: ['2.25.202610120001.1'] },
'00280002': { vr: 'US', Value: [1] },
'00280004': { vr: 'CS', Value: ['MONOCHROME2'] },
'00280010': { vr: 'US', Value: [2] },
'00280011': { vr: 'US', Value: [2] },
'00280100': { vr: 'US', Value: [8] },
'00280101': { vr: 'US', Value: [8] },
'00280102': { vr: 'US', Value: [7] },
'00280103': { vr: 'US', Value: [0] },
'7FE00010': { vr: 'OB', InlineBinary: 'ACCA/w==' }
};
const generated = await EASI.pipelineBuilder()
.fromByteStream()
.ofDicomMetadata()
.toDicomData()
.build()
.process({ source: new TextEncoder().encode(JSON.stringify(metadata)) });
const dicomBytes = generated.first();
const directory = await mkdtemp(join(tmpdir(), 'easi-manifest-'));
try {
const path = join(directory, 'synthetic.dcm');
await writeFile(path, dicomBytes);
console.log(JSON.stringify(await buildDatasetManifest(path), null, 2));
} finally {
await rm(directory, { recursive: true, force: true });
}Generated sample data. Complete setup included.
Parse a DICOM upload stream and write serialized chunks to your storage sink through one pipeline.
Write chunks without collecting the entire output.
import EASI from '@xinonix/easi-js';
async function storeUpload(uploadStream, saveChunk) {
const result = await EASI.pipelineBuilder()
.fromNodeStreamAdapter()
.ofDicomData()
.withBulkDataPolicy({ mode: 'auto' })
.toDicomData({
collectOutput: false,
onChunk: saveChunk
})
.build()
.process({ source: uploadStream });
return result.first();
}
// Runnable synthetic example. A real server supplies its request and storage sink.
import { createReadStream } from 'node:fs';
import { mkdtemp, open, rm, stat } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable } from 'node:stream';
// Generate a tiny raw DICOM dataset for learning, not a clinical image.
const metadata = {
'00080016': { vr: 'UI', Value: ['1.2.840.10008.5.1.4.1.1.7'] },
'00080018': { vr: 'UI', Value: ['2.25.202610120001.1.1'] },
'00080060': { vr: 'CS', Value: ['OT'] },
'00100020': { vr: 'LO', Value: ['SYNTHETIC-EXAMPLE'] },
'0020000D': { vr: 'UI', Value: ['2.25.202610120001'] },
'0020000E': { vr: 'UI', Value: ['2.25.202610120001.1'] },
'00280002': { vr: 'US', Value: [1] },
'00280004': { vr: 'CS', Value: ['MONOCHROME2'] },
'00280010': { vr: 'US', Value: [2] },
'00280011': { vr: 'US', Value: [2] },
'00280100': { vr: 'US', Value: [8] },
'00280101': { vr: 'US', Value: [8] },
'00280102': { vr: 'US', Value: [7] },
'00280103': { vr: 'US', Value: [0] },
'7FE00010': { vr: 'OB', InlineBinary: 'ACCA/w==' }
};
const generated = await EASI.pipelineBuilder()
.fromByteStream()
.ofDicomMetadata()
.toDicomData()
.build()
.process({ source: new TextEncoder().encode(JSON.stringify(metadata)) });
const dicomBytes = generated.first();
// Simulate an upload whose chunks cross DICOM attribute boundaries.
function* incomingChunks() {
for (let offset = 0; offset < dicomBytes.length; offset += 17) {
yield dicomBytes.subarray(offset, offset + 17);
}
}
const uploadStream = Readable.from(incomingChunks());
const directory = await mkdtemp(join(tmpdir(), 'easi-upload-'));
try {
const destination = join(directory, 'stored.dcm');
const storage = await open(destination, 'w');
let position = 0;
let writeChunks = 0;
const saveChunk = async chunk => {
let offset = 0;
while (offset < chunk.byteLength) {
const { bytesWritten } = await storage.write(
chunk, offset, chunk.byteLength - offset, position);
if (bytesWritten === 0) throw new Error('Storage write made no progress.');
offset += bytesWritten;
position += bytesWritten;
}
writeChunks++;
};
let receipt;
try {
receipt = await storeUpload(uploadStream, saveChunk);
} finally {
await storage.close();
}
// Check this generated fixture without loading the stored file into memory.
const storedHash = createHash('sha256');
for await (const chunk of createReadStream(destination)) storedHash.update(chunk);
console.log(JSON.stringify({
bytesWritten: receipt.bytesWritten,
storedBytes: (await stat(destination)).size,
writeChunks,
storedSha256: storedHash.digest('hex'),
sourceSha256: createHash('sha256').update(dicomBytes).digest('hex')
}, null, 2));
} finally {
await rm(directory, { recursive: true, force: true });
}Generated sample data. Complete setup included.
Read a user-selected File or Blob and return the metadata your interface needs, locally in the browser.
A file in. The fields your UI needs out.
import EASI, { Tag } from '@xinonix/easi-js';
async function inspectDicomFile(file) {
const selection = EASI.selectionBuilder()
.include([Tag.Modality, Tag.Rows, Tag.Columns])
.build();
const result = await EASI.pipelineBuilder()
.fromFileStream()
.ofDicomData()
.withBulkDataPolicy({ mode: 'auto' })
.toSelection(selection)
.build()
.process({ source: file });
const attributes = result.first();
return {
modality: attributes.value(Tag.Modality),
rows: attributes.value(Tag.Rows),
columns: attributes.value(Tag.Columns)
};
}
// Runnable synthetic example. In your app, use the File from a file input.
// Generate a tiny raw DICOM dataset for learning, not a clinical image.
const metadata = {
'00080016': { vr: 'UI', Value: ['1.2.840.10008.5.1.4.1.1.7'] },
'00080018': { vr: 'UI', Value: ['2.25.202610120001.1.1'] },
'00080060': { vr: 'CS', Value: ['OT'] },
'00100020': { vr: 'LO', Value: ['SYNTHETIC-EXAMPLE'] },
'0020000D': { vr: 'UI', Value: ['2.25.202610120001'] },
'0020000E': { vr: 'UI', Value: ['2.25.202610120001.1'] },
'00280002': { vr: 'US', Value: [1] },
'00280004': { vr: 'CS', Value: ['MONOCHROME2'] },
'00280010': { vr: 'US', Value: [2] },
'00280011': { vr: 'US', Value: [2] },
'00280100': { vr: 'US', Value: [8] },
'00280101': { vr: 'US', Value: [8] },
'00280102': { vr: 'US', Value: [7] },
'00280103': { vr: 'US', Value: [0] },
'7FE00010': { vr: 'OB', InlineBinary: 'ACCA/w==' }
};
const generated = await EASI.pipelineBuilder()
.fromByteStream()
.ofDicomMetadata()
.toDicomData()
.build()
.process({ source: new TextEncoder().encode(JSON.stringify(metadata)) });
const dicomBytes = generated.first();
const file = new File([dicomBytes], 'synthetic.dcm', { type: 'application/dicom' });
console.log(JSON.stringify(await inspectDicomFile(file), null, 2));Generated sample data. Complete setup included.
STREAMING YOU CAN SEE
Watch each instance reach your application as the rest of the stream continues.
EASI.pipelineBuilder()
.fromPartStream()
.ofDicomData()
.withBulkDataPolicy({ mode: 'auto' })
.withOnEmit(showLatestInstance)
.toInstances()
.build();
This replay supplies a generated byte stream. DICOMweb, uploads, and files can feed the same parser.
Waiting for the first instance
Synthetic DICOM stream · Real EASI JS parsing · Runs in your browser. Delivery is paced to make the stream visible.
FROM PIPELINE TO PIXELS
Build the foundation of a zero-footprint viewer. EASI JS reads the file, parses DICOM, and decodes its pixels. Your application puts them on screen.
import EASI from '@xinonix/easi-js';
import { Image } from '@xinonix/easi-js/dicom';
// A native little-endian monochrome DICOM File; rendering retains pixel bytes.
async function viewDicom(file, canvas) {
const result = await EASI.pipelineBuilder()
.fromFileStream()
.ofDicomData()
.withBulkDataPolicy({ mode: 'materialize', hardSafetyCap: 64 * 1024 * 1024 })
.toInstances()
.build()
.process({ source: file, sourceOptions: { contentType: 'application/dicom' } });
const image = new Image(result.first().dataSet);
const { rows, columns } = image.imagePixelModule;
const pixels = new Uint8Array(rows * columns * 4);
const frameIndex = 0; // Zero-based: choose any supported frame.
if (!image.decodeFrame(pixels, null, frameIndex)) throw new Error('Unsupported image pixels.');
canvas.width = columns;
canvas.height = rows;
canvas.getContext('2d').putImageData(
new ImageData(new Uint8ClampedArray(pixels), columns, rows), 0, 0
);
}The viewer retains pixel data for decoding. The stream replay above shows the alternative when only metadata is needed.
Small viewer demonstration, built on EASI JS 1.0.1. Supports common native little-endian and baseline JPEG images; other encodings show a clear message. This is a foundation for an application viewer, not a diagnostic tool.
MR, CT, and X-ray samples are derived from the provided anonymized collection with identifying metadata omitted; the X-ray is reduced for faster loading. US is a generated ultrasound-style cine demonstration. Local files are never uploaded. Sample details
A SMALL EXAMPLE. A REAL PIPELINE.
Choose a synthetic sample and an output. EASI JS runs here in your browser, so you can see the transformation for yourself.
Tiny generated datasets with fictional identifiers. No patient files are loaded or uploaded.
Preparing the synthetic sample…Loading the example…Choose an output and run the pipeline.This demonstrates metadata processing using small synthetic DICOM datasets. It is not a clinical viewer or a diagnostic tool.
BEYOND THE FIRST FILE
Produce FHIR R4 ImagingStudy resources. Set patient references and other application context deliberately, with the mapping guide at hand.
Explore FHIR mapping NODE.JS + DIMSEVerify a peer, store instances, and use supported Study Root query/retrieve with Node.js DIMSE client and server APIs.
Explore DIMSE supportEASI JS is a library for imaging workflows. Your application supplies its UI, identity, storage, and deployment. Some pixel formats need optional codec backends.
Understand the boundariesFROM FIRST RUN TO YOUR APPLICATION
Start with a complete example, then use the guides and public source to adapt the pipeline to your own project.
Install the package, generate a tiny synthetic dataset and run a complete example. No archive or patient files required.
Follow the quick startLearn sources, selections, mappings, writing and memory decisions, then connect HTTP sources or a DICOM peer.
Explore pipeline conceptsFind browser and Node.js recipes, custom mappings, pixel data, API references and troubleshooting in the package usage guide.
Read the complete EASI JS guideTHE FOUNDATION. YOUR NEXT STEP.
Use the library on its own, or choose an independent EASI product that puts the pipeline to work. Each has its own package, documentation and release cycle.
PUBLIC SOURCE. ROOM TO GROW.
Source-available under the EASI JS Community License. Free use is available to eligible individuals, qualifying research institutions and nonprofits, and organization groups with annual gross revenue strictly below US$5 million.
Larger organization groups need written commercial terms unless a stated exception applies. Proprietary applications and distribution follow the full license.
Source-available, not an OSI-approved open-source license. Read the full EASI JS license.