Consuming Matterport E57 Files

Scope

How a Matterport capture reaches ReqTwin as an E57 file, what that file does and does not contain, and the two things about its imagery that are easy to get wrong. Assumes you have read "Working with Reality Capture Scans".

Why E57

E57 is the only route to Matterport geometry. The Model API serves panoramas, tags and floorplans, but no point cloud, so the export is what carries the survey.

The export is bought by the customer, on their own Matterport account, and handed to ReqTwin like any other contractor deliverable. ReqTwin makes no API call and stores nothing belonging to the Matterport platform.

The export stays downloadable from that Space's Downloads tab, which matters for verification: a reader-side fix changes no stored row, so re-running the import against the original file is the only way to prove the fix worked.

What the file contains

Measured against a real Matterport export:

The six images are the faces of a cube map. Together they cover every direction from one position, which is the same coverage a 360 panorama gives, delivered as six flat images instead of one distorted one.

Two things that are easy to get wrong

These are recorded because both fail silently: they produce plausible numbers, no error and no warning.

One station per place, not per image

The six faces of a sweep share a single position and differ only in rotation. A station per image would put six coincident pins on the map for one place a person stood, and would make every station count six times too large.

ReqTwin groups faces on associatedData3DGuid first and position second. The link is what the exporter actually asserts about which sweep a face belongs to; grouping on a rounded position is a heuristic that would merge two genuinely different sweeps sitting a millimetre apart, which a stairwell directly above another produces.

The station's own heading is therefore null, with orientationSource set to multi-face. That is richer than "absent", not poorer: a station that sees in every direction has no single facing, exactly as a 360 pano does not, and the "front" of a cube map is an arbitrary label. The real orientations live per face in the station's cameras.

A pinhole camera looks along +Z, not +X

A spherical image's projection ties its centre column to local +X, so a panorama is x-forward and that falls out of the equations. A pinhole camera uses the ordinary x-right, y-down, z-forward convention.

Measuring the wrong axis reports the direction the camera's *right edge* faces. On a cube-mapped sweep that collapses six faces onto four headings with no vertical face among them, while every face still returns a believable bearing.

The test that settles it, on any cube-mapped file: rotate each body axis by all six face quaternions and count distinct directions.

Only +Z describes a cube. Read correctly, a sweep gives four horizontal faces exactly 90 degrees apart plus one looking straight up and one straight down.

Note that a near-vertical face's heading is not meaningful: at ±90 degrees of pitch, heading and roll are one degree of freedom, so the value is an artefact of how the exporter happened to roll that face. Its pitch is what tells you it points up or down.

Back-projecting a detection

A pinhole image cannot be back-projected from pixels alone; it needs its intrinsics, which ReqTwin reads as a set from pinholeRepresentation. A partial set is treated as no camera rather than a degraded one, because defaulting the principal point to half the image width silently shifts every detection by the real offset.

Units are E57's own and mixing them is the obvious trap: focal length and pixel pitch are metres on the sensor; the principal point is pixels. A ray in the camera frame for pixel (u, v) is

normalize( (u - ppx) * pixelWidth,
           (v - ppy) * pixelHeight,
           focalLength )

before the face's pose rotates it into the file frame.

Tagging is ReqTwin's, not Matterport's

E57 has no annotation concept at all, and Matterport writes none, so a customer's Mattertags do not travel with the export.

This is not a gap to work around. Tagging in ReqTwin is ReqTwin's own: detections carry their position, classification, confidence and review state, and they are joined to the BIM asset register rather than being free text pinned to a picture. That is what makes a tag answer "is this asset where the model says it is" instead of "someone wrote a note here". A customer moving from Matterport to ReqTwin is not losing tags, they are moving from annotation to an asset record.

Mattertags remain reachable through the Model API if a customer wants their existing markup imported as a starting point, and delegated access covers that at no cost to ReqTwin. It is enrichment, never a dependency.

The viewer is ReqTwin's too

The capture is rendered in ReqTwin's own viewer: the point cloud from the E57, standing at each capture position, with the imagery from that sweep. The Matterport Showcase embed is not needed, and nothing in the workflow depends on their viewer being available.

An E57 is a snapshot

The file records the building as it was when the export was taken, and it works indefinitely. It stays re-downloadable from that Space's Downloads tab for as long as the Space exists.

Progressive capture, comparing this month against last, needs new scans, and new scans are an activity on the customer's own Matterport account. That is a decision about their capture programme rather than about ReqTwin, and it is better said early than discovered later.

Zoom at a capture position

A Matterport Pro3 reaches roughly 100 m, so a good deal of what a capture records sits well beyond what a 60 degree view resolves on a screen. The viewer therefore zooms at each station: scroll, or + / -, with 0 to reset, and a magnification badge appears while you are zoomed.

Zoom is implemented as a narrowing field of view, never as moving the camera forward. The whole model of this viewer is that you stand AT a capture position and only your aim changes, and a camera that crept forward would silently stop being at the station its pose, its heading and every back-projected detection assume. The map's view cone narrows to match, which is honest for zoom in a way it would not be for tilt: tilting does not change how wide the camera sees, but zooming does.

Two limits worth knowing. Below about 15 degrees the point cloud's own spacing becomes the constraint, so further zoom magnifies the gaps between points rather than revealing anything new. And zoom cannot create detail the capture never recorded: at 100 m even a high-resolution sweep resolves little, so use it to read what is there rather than to expect what is not.

Checking an import went well

The import report answers the only question that matters before anyone builds on the data: how many panos carry a real facing. A file whose faces are all identity rotations imports its geometry perfectly and can back-project nothing, and the count is what tells you so.

Expect, per sweep: one station, six cameras, four horizontal headings 90 degrees apart, one face near +90 pitch and one near −90.