# Twinbly file preparation requirements Requirements version: 1. Reviewed November 3, 2026. Use these requirements with the [readable preparation prompts](https://www.twinbly.com/learn/processing-workflows#prepare-with-your-ai). The same prompts are available as [Markdown](https://www.twinbly.com/learn/guides/processing-workflows.md). Re-read this document when preparing a new capture. The browser's current eligibility, preview and price review remain authoritative. ## Preserve evidence Keep original files unchanged. Work in a new output folder and retain a filename mapping and a short preparation report. Do not invent coordinates, heights, calibration, camera poses, correction status or missing footage. Do not rename extensions to force acceptance. Never turn ordinary GPS into a supposedly corrected geotag file. File preparation does not authorize uploading, paid processing or publication. ## Photos and ordinary video — Create Create accepts a photo ZIP or supported video. Its photo reader recognizes JPG/JPEG, PNG, HEIC/HEIF, TIF/TIFF and WebP; decoding still depends on the actual file and browser. Preserve metadata and image quality. Exclude thumbnails, unrelated media and duplicate names from a prepared ZIP. Do not put an E57, streamed splat folder or prepared reconstruction into a photo ZIP and expect it to become a photo capture. Keep original MP4/MOV parts in chronological order. Separate unrelated recordings. Use Twinbly's preview to inspect coverage and choose the processing plan. Preparation cannot add missing viewpoints or recover lost detail. ## Survey photos and positioning Select a parent folder with the original flight subfolders and sidecars. The survey metadata scan recognizes JPG/JPEG, PNG, TIF/TIFF, HEIC and DNG. Current Survey intake needs at least 80 positioned photos. That is an intake threshold, not a coverage guarantee. Survey and Create have different input paths; do not assume their format lists are interchangeable. An existing corrected geotag export can use comma-separated columns: ```csv image,latitude,longitude,altitude ``` Use decimal degrees for latitude/longitude and metres for altitude. Confirm the source coordinate reference and height datum from the correction export; do not transform an unknown system or assume an orthometric height is ellipsoidal. Keep full precision. Accepted image headers include image, img, file, filename, file name, name and photo. Latitude accepts lat/latitude; longitude accepts lon/lng/long/longitude; height accepts alt/altitude/elevation/ellipsoidal height/height/z. Rows join to photos by **case-insensitive basename**, even if the CSV contains a folder path. Two flights both containing `IMG_0001.JPG` are ambiguous in one combined selection. Do not flatten folders or rename only one side of a mapping. Resolve the source association explicitly, preserving originals and recording any coordinated rename in prepared copies. Check every row, missing photo references, repeated names, latitude/longitude ranges, and absent heights. Matched CSV positions override photo EXIF; unmatched photos can retain EXIF positions. Review partial coverage. Missing heights can otherwise be treated as zero by the intake, so preparation must flag them rather than manufacture certainty. RTK metadata and corrected-position exports provide evidence to review. Neither a camera brand nor a parsed CSV guarantees survey accuracy. Raw OBS/NAV/RINEX/MRK and similar logs are inputs to a correction workflow, not evidence that it ran. Obtain a documented corrected export when PPK is required; the local checker does not perform PPK. ## Drone video sidecars Keep each MP4/MOV and original SRT together with matching filename stems, such as `flight01.MP4` and `flight01.SRT`. Avoid repeated stems across flights in one selection. Supported DJI captions contain bracketed latitude/longitude fields and frame counters. Older positional GPS-triple dialects may be unsupported. Do not fabricate missing captions or telemetry. Caption-derived positions remain GPS guidance, not RTK certification. Twinbly handles frame extraction in its supported workflow. The local checker does not compare video duration with caption timing or decode video. Review that association and the selected workflow in the [drone guide](https://www.twinbly.com/learn/drone-photos-and-video). ## Insta360 Use original compatible INSV files from one recording, including consecutive parts where supported, or a stitched full 2:1 equirectangular MP4. A reframed flat export, LRV preview or thumbnail is not a substitute. Do not combine separate lens files by concatenation. Check the [current Insta360 guide](https://www.twinbly.com/learn/insta360-x5-gaussian-splats) for supported selections and limits; an aspect ratio alone does not prove spherical content. ## Matterport Use one original Matterport E57 with spherical images, up to 50 GiB (53,687,091,200 bytes). Keep the vendor download unchanged. A generic E57 or MatterPak point cloud can lack the panoramas this workflow needs. Re-exporting through another tool can remove required data. Choose the E57 in Create when Matterport import is available for your account. Review its scanner count and quote before processing. See [Matterport preparation](https://www.twinbly.com/learn/matterport). Passing header/XML checks is not proof that all payloads, CRCs or poses are valid or that automatic placement will work. ## Existing splats and prepared reconstructions The existing-splat picker accepts single-file PLY or SOG. An ordinary mesh/point-cloud PLY is not necessarily a Gaussian splat. Preserve streamed manifests and relative sibling chunks; that folder is not a single-file import. Do not rename extensions or merge chunks to manufacture one. Prepared reconstruction and cloud-manifest inputs belong to documented API workflows. Follow the [developer guide](https://www.twinbly.com/developers/guide.md) and its current schema for layout, image references and access requirements. Do not assume those bundles are accepted by the browser's photo ZIP lane. ## Optional local checker Download [twinbly-preparation-check.cjs](https://www.twinbly.com/learn/preparation/twinbly-preparation-check.cjs) and read it before execution. It is a standalone Node 20+ script; no package installation, account credentials or network access are needed when running it. If Node is unavailable, use Twinbly's browser preflight instead. Run from the directory where you saved the script, replacing the folder path: ```sh node twinbly-preparation-check.cjs survey "/path/to/survey-folder" node twinbly-preparation-check.cjs matterport "/path/to/folder-with-one-e57" ``` The checker reads local metadata and prints a JSON report. It does not write files, follow symbolic links, upload data or start processing. Paths in the report are relative to your selected folder; review filenames before sharing. It checks at most 100,000 directory entries and 32 MiB per text sidecar. E57 reads are limited to its header and bounded XML metadata. A size/read limit or skipped input is reported; it is not silently certified. Exit codes: **0** means no blocking findings in the checks performed, **1** means findings need attention, **2** means usage or incomplete execution. Always read warnings and limits, even after exit 0. It does not decode image/video pixels, inspect ZIPs, prove geodetic accuracy, verify all E57 payloads or guarantee processing success. It is optional assistance, not a prerequisite or replacement for the upload preview. ## Preparation report Ask your assistant for: source inventory; the exact prepared selection; changes and filename mappings; checks actually run; warnings and blockers; unresolved provenance or coordinate questions; and the next action in Twinbly. Keep credentials, signed URLs and personal local paths out of any report you share.