This specifies what ReCap imports from .e57 files and how those structures are interpreted. Terminology follows libE57 / ASTM E2807; where the spec is silent, behavior aligns with ReCap’s implementation.

General file-level requirements

• ReCap accepts .e57 file conforming to ASTM E2807.
• The main used nodes are Data3D and Images2D (optional for scans with imagery data).
• Per‑scan pose is applied when present. If absent/identity, a spherical Image2D.pose may be used to define the scan pose.

Point cloud data

Per‑point fields: mandatory and optional

• Position (at least one of the following is required):
  • Cartesian: cartesianX , cartesianY , cartesianZ (double)
  • Spherical*: sphericalRange , sphericalAzimuth , sphericalElevation (double) If only spherical is present, Cartesian is reconstructed from range/angles.
• Optional attributes (imported when present):
  • Intensity: numeric
  • Color: colorRed , colorGreen , colorBlue (integer per E57; typically 16‑bit)
  • Normals
  • Structured indices: rowIndex , columnIndex
  • Validity masks: cartesian/spherical invalid flags; respected when available
  • timeStamp , returnCount , returnIndex , amplitude , reflectance

Per‑scan metadata used (optional)

• pose (translation + quaternion/rotation)
• indexBounds / declared row & column counts: declare structured layout when consistent with points.
• colorLimits / intensityLimits : used to normalize color/intensity to UI ranges.
• sphericalBounds : used for partial scans and azimuth/elevation interpretation.
• guid , name , sensorVendor , sensorModel : used for image association and vendor‑specific defaults.

Unstructured scans

ReCap treats any e57 scan without structure indexes (rowIndex, columnIndex) as not structured. If the scans have spherical images, ReCap is able to use the imagery date to convert unstructured scan to structured scan (image import option) For unstructured scans, ReCap only imports Data3D data.

Structured scans

In ReCap several types of e57 can be treated as structured:

• When per‑point rowIndex and columnIndex are present and valid:
• For the cases when structured indices are not present, but there is associated spherical Image2D

Structured indices scans

• If spherical image is provided, ReCap is able to import imagery data and map it to row/columns indexes (image import option)

• If spherical image isn't available, Recap will recreate panoramic representation from point cloud data and map alignment using rowIndex and columnIndex.

Associated with spherical representation scans

• The scan can be treated as structured when an associated spherical Image2D exists and image import is enabled.
• Default orientation when not otherwise specified: azimuth start π , elevation start π/2 . Note: for some vendors these parameters might be different.
• Pixel mapping per row/column index reconstruction is done with the usage of pixelWidth and pixelHeight .
• If scan pose is missing/identity, the image pose (Image2D.pose ) may define the scan pose.

Panoramic imagery

• ReCap supports only E57_SPHERICAL representation.
• Both JPEG or PNG images with a valid header are acceptable and being decompressed at import.
• Image is associated to a scan via associatedData3DGuid.
• The image rotation/translation (Image2D.pose ) are applied for alignment.

Required E57 fields and minimal schemas

• Data3D points (CompressedVector)

• Image2D (spherical) — required fields

XML sample:

Special cases

Single pointcloud with several spherical representations

ReCap support e57 file containing point cloud data and multiple panorama images for each scan. Multiple spherical Image2D entries that reference the same Data3D scan are supported. Depending on the user's choice, additional images can be imported individually when needed (for example with create‑per‑image workflows).

Association key: Image2D.associatedData3DGuid must match the target Data3D.guid. Images with empty or non‑matching associations are not applied to a scan; they may still be imported as image‑only entries if enabled.

XML sample:

Resolution mismatch handling

A resolution mismatch occurs when the scan resolution (point cloud data: rows × columns) is greater than the panoramic image resolution (image width × height). This can result in black areas in RealView, where scan points lie outside the image coverage.

Depending on the user's choice during import, the scan's resolution or image resolution can be used for spherical representation recreation (RealView).

XML sample:

Image Orientation - Level Panoramic Image

ReCap expects the panoramic image that comes from the E57 file to have horizontal orientation that aligns with the scan orientation. But in some scenarios, the camera is not always upright, and the panoramic image is not horizontal. This can result in misalignment in RealView or weird navigation during orbiting and rotating.

Depending on user’s choice during import, ReCap may use the scan orientation to adjust the panoramic image for spherical representation recreation (RealView).

XML sample: