e57-js

JavaScript library for reading and writing E57 point cloud files, compatible with Node.js and the browser.

What is a point cloud? A point cloud is a collection of 3D points in space, typically captured by a laser scanner (LiDAR). Each point has X, Y, Z coordinates and optionally colour, intensity, and other data. E57 is the standard file format for storing them.

---

Installation

npm install e57-js

Requires Node.js 18 or higher, or any modern browser with WebAssembly support.

In the browser, file-system access is not available — use E57Reader.FromBuffer(buffer) to read from a Uint8Array and E57Writer.ToBuffer() to write to one.

---

Setup

Before doing anything, call E57.Init() once and wait for it to finish. This loads the underlying WebAssembly module.

import { E57, E57Reader, E57Writer, E57WriterScan, E57WriterImage } from 'e57-js'

await E57.Init()

// Now you can create readers and writers

---

Reading a file

Open the file

// From a file path (Node.js)
const reader = new E57Reader('scan.e57')

// From a buffer (browser or Node.js)
const reader = E57Reader.FromBuffer(buffer)  // buffer is a Uint8Array

console.log(reader.GetData3DCount())   // number of 3D scans
console.log(reader.GetImage2DCount())  // number of embedded images

Read the points from a scan

const scan = reader.GetScan(0)  // get the first scan (index 0)

const header = scan.GetHeader()
console.log(`This scan has ${header.pointCount} points`)

// Read all points at once
const points = await scan.ReadScan()

for (let i = 0; i < points.size(); i++) {
    const pt = points.get(i)
    console.log(pt.cartesianX, pt.cartesianY, pt.cartesianZ)
}

// free WASM memory when done
points.delete()

Read in chunks (better for large files)

Reading millions of points all at once can use a lot of memory. Use ScanPoints to process them in smaller batches:

await scan.ScanPoints(1000, (chunk) => {
    for (let i = 0; i < chunk.size(); i++) {
        const pt = chunk.get(i)
        // process pt...
    }
    // chunk is freed after this callback returns — do not hold references to it outside
})

Apply the scan pose (position and orientation)

A scan's pose describes where the scanner was placed in the world. When you read with ReadScan() the pose is applied automatically — the returned coordinates are already in world space.

Pass false to get the raw local coordinates instead:

const worldPoints = await scan.ReadScan()        // world coordinates (default)
const localPoints = await scan.ReadScan(false)   // raw scanner-local coordinates

Read an embedded image

const image = reader.GetImage(0)
const header = image.GetHeader()
console.log(header.width, header.height)

// Get the image as a byte buffer
const bytes = await image.ReadImage()  // Uint8Array
// use bytes...
image.Release(bytes)  // free WASM memory when done

// Or save it directly to disk (extension is auto-detected — memory is freed automatically)
await image.Save('output')   // writes output.jpeg or output.png

Synchronous versions

Every async method has a sync equivalent if you prefer blocking calls:

const points = scan.ReadScanSync()
const bytes  = image.ReadImageSync()

Exception: AddImage has no sync version.

---

Writing a file

Create the file

// To a file path (Node.js)
const writer = new E57Writer('output.e57')

// To a buffer (browser or Node.js) — Close() returns a Uint8Array
const writer = E57Writer.ToBuffer()

Write a 3D scan

import { E57WriterScan } from 'e57-js'

const scan = new E57WriterScan()
scan.GetHeader().guid = 'my-unique-scan-id'
scan.GetHeader().pointFields.cartesianXField = true
scan.GetHeader().pointFields.cartesianYField = true
scan.GetHeader().pointFields.cartesianZField = true

for (let i = 0; i < 100; i++) {
    const pt = new E57.LibE57.Point()
    pt.cartesianX = i * 0.1
    pt.cartesianY = 0
    pt.cartesianZ = 0
    scan.AddPoint(pt)
}

const scanIndex = await writer.AddScan(scan)
scan.Destroy()

Write a scan with colour

const scan = new E57WriterScan()
scan.GetHeader().pointFields.cartesianXField = true
scan.GetHeader().pointFields.cartesianYField = true
scan.GetHeader().pointFields.cartesianZField = true
scan.GetHeader().pointFields.colorRedField   = true
scan.GetHeader().pointFields.colorGreenField = true
scan.GetHeader().pointFields.colorBlueField  = true
scan.GetHeader().colorLimits.colorRedMaximum   = 255
scan.GetHeader().colorLimits.colorGreenMaximum = 255
scan.GetHeader().colorLimits.colorBlueMaximum  = 255

const pt = new E57.LibE57.Point()
pt.cartesianX = 1.0; pt.cartesianY = 2.0; pt.cartesianZ = 3.0
pt.colorRed = 255; pt.colorGreen = 0; pt.colorBlue = 0
scan.AddPoint(pt)

Set the scanner position (pose)

If you know where the scanner was placed, you can store that as a pose. Use an identity quaternion (w=1, x=0, y=0, z=0) if there is no rotation:

scan.GetHeader().pose.rotation.w = 1.0
scan.GetHeader().pose.rotation.x = 0.0
scan.GetHeader().pose.rotation.y = 0.0
scan.GetHeader().pose.rotation.z = 0.0
scan.GetHeader().pose.translation.x = 10.0   // scanner was 10 m east
scan.GetHeader().pose.translation.y = 20.0   // 20 m north
scan.GetHeader().pose.translation.z = 1.5    // 1.5 m above ground

Write an image

import { E57WriterImage } from 'e57-js'

// From a file path (Node.js)
const image = new E57WriterImage(
    'photo.jpg',
    E57.LibE57.Image2DType.ImageJPEG,
    E57.LibE57.Image2DProjection.ProjectionVisual
)
image.SetName('Front camera')

await writer.AddImage(image)
image.Destroy()

In the browser, use E57WriterImage.FromBuffer instead:

// From a Uint8Array (browser or Node.js)
const image = E57WriterImage.FromBuffer(
    buffer,                                          // Uint8Array
    E57.LibE57.Image2DType.ImageJPEG,
    E57.LibE57.Image2DProjection.ProjectionVisual
)
image.SetName('Front camera')

await writer.AddImage(image)
image.Destroy()

Close the file

Always call Close() when you are done. This finalises the file — skipping it will produce a corrupt file.

writer.Close()  // returns a Uint8Array only when the writer was created with E57Writer.ToBuffer()

---

Point fields reference

Field	Description
cartesianX / Y / Z	3D position in metres
colorRed / Green / Blue	RGB colour (0–255 or 0–65535)
intensity	Reflected signal strength
sphericalRange / Azimuth / Elevation	Position in spherical coordinates
normalX / Y / Z	Surface normal vector
timeStamp	When the point was captured
rowIndex / columnIndex	Grid position (structured scans)
returnIndex / returnCount	Multi-return laser data

The fields a scan actually contains depend on how it was written. Check scan.GetHeader().pointFields to see which ones are present.

---

For more examples of how to read and write E57 files with this library, have a look at the test files:

• tests/io.test.js — synchronous read/write examples
• tests/io.async.test.js — async read/write examples

---

License

MIT License