rOrtho 3D Photo Engine

User manual

Version 0.1.2by iGageigage.com

rOrtho turns a folder that CoPre2 exported from your CHCNAV RS7 into files your other software opens: an orthophoto and a height map on real map coordinates, photos that know where they were taken, and the mesh (the 3D surface CoPre2 builds from the scan) as one file. It is one program with three jobs, runs on your computer and needs no internet.

What you get

Each job takes one folder from a CoPre2 export and writes one new folder beside it. This manual numbers the jobs as below. The window does not number them, and it lists Make an orthomosaic first.

Getting started

1. Copy rOrtho.exe anywhere: the desktop, a USB stick or a shared drive. There is nothing to install and no second file to keep beside it.

2. Double-click it. The start window opens and asks What do you want to make?

   The first time, a note explains that nothing is written until you press the big button on a job screen. Press Got it to dismiss it. Until a registration code is entered, the start window is locked and says so; see The small print.

3. Press Choose a CoPre2 folder... and pick a folder. rOrtho looks inside, works out which job the folder is for, and opens that job with the folder filled in. You can also drop the folder on the window, or drop its metadata.xml.

   Each card also has its own Choose folder... button, which opens that job directly. The tree drawn on each card is what to match against Explorer.

4. Read the job screen top to bottom, then press the one blue button. Every job screen has the same three numbered sections on the left: 1. Folder in, 2. Folder out, 3. Options. The right side shows progress, the log and the result.

What each job asks for and gives back

Job	Folder in	Folder out (created beside the folder in)
Make an orthomosaic	The Model folder: it has metadata.xml and an OBJ folder inside. Usually under AUTOSOLVE, sometimes named Model(1).	rOrtho-ortho, holding ortho.tif, ortho_dsm.tif and their world and projection files.
Prep photos for photogrammetry	The AUTOSOLVE folder with Camera1, Camera2 and Scanner1 inside, under Results\Export\<project>.	rOrtho-photos: the package, with the photos, a folder per piece of software, a README and a report.
Combine mesh tiles	The same Model folder, or the OBJ folder inside it.	rOrtho-mesh, holding one .obj, one .mtl, every texture image and georef.txt.

If the default folder out already exists and has files in it, rOrtho proposes rOrtho-ortho-2, then -3, so a second run never lands on the first. You can always press Choose... and pick another folder beside the export.

The job screen

• The line under the folder box is the first thing to read. Green means the folder fits. Amber means something to fix, in a sentence that names it. The blue button stays off until the folder is one rOrtho recognises.
• The blue button is the only thing that writes. While a job runs it becomes Stop.
• The status line on the right says what is happening in words and how long it has taken, for example Working: Rendering tile 5 of 6 - 0:01, then Done in 0:03.
• Log (for support) shows everything the engine says. It is also saved as rortho-gui.log in the folder out. Result shows what was made and what to do with it.

Stopping is safe. Prep photos finishes the current step and leaves nothing half-written. The orthomosaic stops at once, so files being written may be incomplete. Combine mesh tiles deletes its half-written .obj. rOrtho will not close while a job is running; stop it or let it finish first.

Job 1: Prep photos for photogrammetry

The RS7 takes photos as it scans. CoPre2 exports them without positions. This job writes where each photo was taken and which way it was pointing into the photo, works out the coordinate system from the scan itself, and writes a folder of files for each piece of photogrammetry software you use.

1. Pick the export. The label reads The export folder with Camera1, Camera2 and Scanner1 inside. It is the AUTOSOLVE folder under Results\Export\<project>.

   When it fits, the line under the box says looks right with the number of photos and whether a point cloud is there. If it says Camera1 is here but holds no photos directly, you picked the processing folder. Pick the export under Results\Export instead.

   

2. Check the folder out. It defaults to rOrtho-photos beside the export. Give it an empty or new folder. If the folder already has files in it, the line under the box turns amber and says rOrtho will refuse to write over them, but the button still works. A run into that folder replaces files with the same names. It also deletes any images folder already there, with everything in it, before it writes the new photos.

3. Choose how the photos are handled.

   Tag the export's own photos (recommended). No copies are made; the pixels are untouched.

   Make tagged copies. The export is never written to. Uses twice the disk.

   The first choice writes the position and heading into the metadata of each photo in the export and lists those photos in the package. The second leaves the export exactly as CoPre2 wrote it and puts tagged copies in the package.

4. Tick the software you will open the photos in. 3Dsurvey is ticked by default; the window spells it 3D Survey. Metashape, Pix4D, ContextCapture, OpenDroneMap, Global Mapper, Any GIS and OpenMVG are the others. Each ticked one gets its own small folder of files in the package, so ticking more than one costs nothing. All and None are there for speed.

   

5. Leave More options closed unless support asks. It holds the settings support may ask you to change: how the ground surface and the photo masks are made, the coordinate system and heights, the raw capture folder, how much of each photo is used, and the number of cores. The coordinate system is worked out from the scan itself. A code you type there is a candidate, checked against the scan's own coordinates and refused if it does not fit.

6. Press Make the package. Check only (writes nothing) runs every check and writes only the report, which is a good first run on a new export.

   The progress block lists the eight steps in order: read the export, work out the coordinate system, build the ground surface from the point cloud, make the photo masks, write the files for your software, tag the photos, check everything that was written, write the report. The Checks tab lists each check with its value and threshold. The Files tab says how many files were written for each piece of software, and lists anything rOrtho declined to write with the reason.

   

   

The result

The Result tab says DONE - your package is ready with the path and four buttons: Open output folder, Open README.txt, Open the report and Open run log.

In the package	What it is
images\	The photos, tagged with position and heading.
packages\<software>\	One folder per piece of software you ticked: the files it imports.
README.txt	Step-by-step import instructions for each piece of software.
rortho-report.html	The report: the coordinate system found, every check and its result.
rortho-manifest.json	The machine-readable record of the run.
rortho-gui.log	The run log.

Under the headline, the Coordinate system block grades what was found: A - on the grid, B - on the grid, weak, or C - no map coordinates. The Photos block says in one sentence what happened to the photos, for example 1,413 photos tagged in place; no copies made.

Job 2: Make an orthomosaic

CoPre2 has already built a textured mesh of the site. This job looks straight down at that mesh and renders a true orthophoto, in which every point is seen from directly above, and a height map at the pixel size you choose. Both come out as GeoTIFFs (images that know where they are on the ground) with a world file and a projection file, so they land in place in a GIS or CAD.

Pick the Model folder

The label reads The mesh folder with metadata.xml and an OBJ folder inside. In Explorer it is the Model folder under AUTOSOLVE. Pick the Model folder itself; the line under the box then says how many tiles the mesh has.

Folder out and file name

The folder out defaults to rOrtho-ortho beside the Model folder. The file name defaults to ortho and makes ortho.tif and ortho_dsm.tif. Use letters, digits, - and _ only. A run into a folder that already has files replaces files with the same names.

Coordinates

This is the one choice that cannot be fixed after the run, so it is first.

Choice	What you get
As scanned (no map coordinates)	The picture in the scan's own frame: metres from wherever the scanner was switched on. It will not land on a map. Use it when you want a picture, or when the scan cannot be placed.
On the ground, US survey feet	A map in the zone the scanner was configured for, in US survey feet. rOrtho recovers where the scan sits from the job's raw GNSS log.
On the ground, metres	The same map, in metres.

What rOrtho fills in for you

When you pick the Model folder, rOrtho reads which coordinate system the scan was configured for and looks near the export for the job's raw GNSS log: the folder holding a file ending _T.gps, often 1-Raw\<job>\GPS\Rover. It searches up to four folders up from the export and four down, and no further. When it finds both the zone and the log, it selects On the ground in the unit the job's own files name and fills in the GNSS folder. When either is missing, it selects As scanned. Once you click a radio yourself, rOrtho stops changing it for that session.

The line under the radios names what was read, for example This scan was configured for NAD83 / New Mexico Central (ftUS) (EPSG:2258). The EPSG code is the number a GIS uses to name a coordinate system. Switching between feet and metres re-words the line: the same zone has one code in feet and another in metres. If the scan's own coordinate-system file could not be read, the line says so instead, and ground coordinates are not possible for that export.

An export that already declares a coordinate system, because the job was processed with GNSS in CoPre2, needs nothing recovered. Its own coordinates go into the products as they are, and the log says so.

The EPSG code box and the amber warning

Leave Coordinate system code (EPSG) empty and the products carry the scan's own code. Type one only when you know your deliverable needs a different one.

When the code you type is not the one the scan declared, an amber line names both. Two codes often describe the same projection on two realisations of NAD83. EPSG:2258 and EPSG:6513 are both New Mexico Central in US survey feet; one is on NAD83 as first published, the other on NAD83(2011). The two realisations sit about a metre apart on the ground, which is a separate matter from the placement accuracy above. rOrtho holds no registry and cannot tell which realisation your control is on, so it names both and leaves the choice with you. Override only when your project control is on the other realisation and you know why.

Pixel size

Pixel size on the ground is in centimetres, and the window suggests 1 cm for an RS7 scan. The presets are 0.5, 1, 2 and 5. Half the pixel size means four times the file size and about four times the wait. On a job in US survey feet, 1 cm becomes 0.0328 ft per pixel in the output, which the Result tab shows.

Leave out everything above takes a height, and anything above it is not drawn. Use it when a roof or a ceiling would hide the floor you want to see. Leave it empty to draw everything.

The number is in the unit the products come out in. When rOrtho can read that unit from the Model folder, it names it beside the box. Choose On the ground, US survey feet and 29.5 means 29.5 US survey feet. Choose metres, or As scanned, and it means 29.5 metres. An export that already declares its own coordinate system keeps its own unit whichever you choose. The height is measured the same way as the heights in the height map (DSM) the run writes. Those are the mesh's own heights, which are not always elevations above sea level (see the warning above). To find a number, run once without a cut and open ortho_dsm.tif, which shows how high the roof or ceiling is. Type a height below the roof or ceiling and above everything you want to see.

More options holds a way to render only part of the site, a choice between smooth and sharp texture sampling, the number of cores, and a box for extra options that support may ask you to type.

Run

Press Make the orthomosaic. The status line follows the engine: reading the mesh, preparing the grid, rendering tile by tile, writing the files. The six-tile site in the figures took 3.5 seconds at 1 cm; larger sites and finer pixels take longer, and the Result tab reports the time of each run. Stop stops at once and may leave incomplete files; run again before using anything in the folder.

The result

File	What it is
ortho.tif	The orthophoto: a colour GeoTIFF, north up, black where there is no mesh. The pixel size, the position and the linear unit are inside the file, and the EPSG code too when one is known.
ortho.tfw	The world file: pixel size and the position of the top-left pixel, for software that reads that instead.
ortho.prj	The coordinate system as text. Written whenever the run had a coordinate system; an As scanned run of a local export writes none, because there is nothing to name.
ortho_dsm.tif	The height map (DSM): one height per pixel, same grid and footprint as the orthophoto, marked as no data where there is no mesh.
ortho_dsm.tfw, ortho_dsm.prj	The same two sidecars for the height map.
ortho_stats.json	The record of the run: grid size, pixel size, unit, coverage, and how the placement was recovered.
rortho-gui.log	The run log.

In a GIS, drag ortho.tif into QGIS, ArcGIS, Global Mapper or your CAD and it lands on the site in the coordinate system and unit you chose. ortho_dsm.tif opens as a raster with one value per pixel; colour it by value to read the heights. Both rasters share one grid, so a pixel in one is the same patch of ground in the other. The Result tab also reports how much of the image has mesh under it; the rest is black in the orthophoto and empty in the height map.

Job 3: Combine mesh tiles

CoPre2 writes a mesh as several OBJ tiles, five or six on the exports rOrtho was tested on, each with its own material file and texture images. This job writes every tile into one .obj with one .mtl and every texture image beside it, so you load one file instead of five or six. The tiles go in as they are: nothing is joined, smoothed or removed, and the file holds exactly what the tiles held.

Pick the Model folder

The label reads The mesh folder with metadata.xml and an OBJ folder inside (the OBJ folder works too). When it fits, the line says how many tiles will become one file, for example Model\OBJ: looks right: a mesh in 5 tiles, to become one .obj.

The folder out defaults to rOrtho-mesh beside the Model folder, and the .obj and .mtl take the folder's name. A folder name with a space is refused, because an .obj reads a space in a file name as two names. There is nothing to set in 3. Options.

Run and result

Press Combine the tiles. A real five-tile job took 2.1 seconds. Stopping deletes the half-written .obj and keeps the textures already copied.

SRSOrigin is a line in georef.txt with three numbers, X, Y and Z: the map coordinates of the point the mesh's local coordinates count from. Add them to a point's X, Y and Z in the .obj to get its map coordinates.

File	What it is
rOrtho-mesh.obj	Every tile in one mesh. Named after the folder out.
rOrtho-mesh.mtl	The one material file, naming every texture.
*.jpg	Every texture image, copied beside the mesh under its own name. Keep them with the .obj.
georef.txt	Where the mesh is: the coordinate system, the origin to add to every vertex, and the unit. The vertices themselves stay in CoPre2's local coordinates.
georef.prj	The coordinate system as text, when the export states one.

3Dsurvey gets one file to load. The textures come with the .obj as long as the .mtl and the .jpg files stay in the same folder. One file also means the viewer decodes every texture image at once; the run log says how much memory that takes, about 2.8 GB for the nineteen images in the example. If a viewer runs out of memory on the merged file, that is why, and the tiles let it load one piece at a time.

If you used rOrtho 0.1.1

Version 0.1.1's third job converted the OSGB copy of the mesh (the other 3D format CoPre2 writes, beside the OBJ tiles), and the window still remembers that folder. Combine mesh tiles works on the OBJ tiles, so the first time you open the job the line under the box says ...\Model\OSGB\Data is the OSGB copy of this mesh. Combining works on the OBJ tiles CoPre writes beside it: pick ...\Model\OBJ instead. Press Use Model\OBJ and carry on.

The small print

Light, dark, or follow Windows

The light theme is a warm paper tone made for sun on the screen. The monitor button follows the Windows setting. One click changes it and the choice is remembered. If the text is too small, hold Ctrl and press +; Ctrl and - goes back.

What rOrtho remembers

Three files, all per user and none beside the executable, so moving or replacing rOrtho.exe costs nothing.

File	What it holds
%APPDATA%\rOrtho\gui-settings.json	The folders and options last used for each job, and the theme. The Last time rows on the start window come from it. Delete it and rOrtho starts with empty boxes.
%LOCALAPPDATA%\rOrtho\license.json	The registration this computer holds.
%APPDATA%\rOrtho\rortho-gui.log	Every run, appended. Each run also writes its own rortho-gui.log in its folder out.

Registration and trial

The three jobs need a registration code. Until one is entered, the start window shows a red box with this computer's ID, and its folder buttons are greyed out. Press Enter a registration code... in the red box, Registration in the bottom bar, or the version number in the header, to open the registration box.

1. Press Copy beside This computer's ID and send the ID to iGage at igage.com.
2. Paste the code you get back into Registration code. Spaces and line breaks do not matter.
3. Press Register. The line at the top turns green and the jobs start working.

A code is made for one computer's ID and works on that computer only. A trial code has an end date, and the registration box says how many days are left. A full code has no expiry. rOrtho never contacts the internet, for registration or anything else.

The registration box also shows the version and the paths of the licence and settings files, so a support call never has to guess where they are.

Where files are written

Every job writes into its folder out, which rOrtho puts beside your export. If you choose a folder out inside the folder in, the line under the box turns amber. Combine mesh tiles then stops with a refusal before it merges anything. Prep photos and Make an orthomosaic run anyway and write their files inside the export, so pick a folder beside it before you press the button. The one thing rOrtho writes inside an export is the position tags of Job 1's recommended choice, Tag the export's own photos, which change the photos' metadata and not their pixels. Choose Make tagged copies to leave the export untouched.

Support

iGage, igage.com. When something goes wrong, press Copy details for support in the bottom bar. It puts the version, the job, both folders, the command line, the result and the last forty log lines on the clipboard. Paste that into an email.

Troubleshooting

rOrtho refuses in a sentence under the thing it is about, never in a dialog you must dismiss. These are the sentences you are most likely to meet and what to do about each.

What you see	Why, and what to do
rOrtho does not recognise <folder>. It looks for a folder with Camera1, Camera2 and Scanner1 (photos), or metadata.xml and OBJ (mesh).	The folder is neither an export nor a mesh folder, and nothing one level down is either. Open it in Explorer and pick the folder that matches the tree on one of the cards.
That folder is not there: <path>. Was the drive or network share disconnected?	A remembered folder has gone. Reconnect the drive, or pick the folder again.
Camera1 is here but holds no photos directly. Pick the export under Results\Export, not the processing folder.	Job 1 was pointed at CoPre2's processing tree. The export with the photos is under Results\Export\<project>\AUTOSOLVE.
Ground coordinates need the job's raw GNSS folder: the GPS folder under the job's raw data, holding a file ending _T.gps. It is the only absolute position anywhere in a scan. Choose it, or switch back to As scanned.	Job 2 could not find the raw GNSS log near the export; it looks four folders up and four down. Press Choose... under The job's raw GNSS folder and pick the folder holding the _T.gps file, often 1-Raw\<job>\GPS\Rover. Or choose As scanned for a picture without map coordinates.
<path>: no raw GNSS log (*_T.gps) here. It lives beside the job's raw data, usually 1-Raw/<job>/GPS/Rover/, not in the export.	The folder you picked for the GNSS log holds no _T.gps file. Pick the GPS folder from the job's raw data, not a folder in the export.
<path>: no .crd in the export, and none given. Without it nothing names the CRS the operator configured.	A .crd file is where the job records the coordinate system (CRS, coordinate reference system) that whoever set up the scan chose in the field. This export has none, so there is no zone to place it in. Use As scanned, or re-export from CoPre2 with the job's coordinate system set.
the export's WKT declares its linear unit as ..., which this tool does not know	WKT (well-known text) is the written-out coordinate system in the export's metadata.xml. Here it names a unit rOrtho does not recognise, and rOrtho refuses rather than guess, because a mesh in feet rendered as metres is 3.28 times wrong in files that look correct. Under More options, in Extra options (for support), type --units us-ft or --units metres, whichever your scan's coordinates are in, and run again.
EPSG <code> is not what the scan declared: it was configured for ... Often the same projection over a different datum realisation, which moves the ground by about a metre - only override if you know why.	Not a refusal. The run goes ahead with your code. Clear the box to keep the scan's own code, or leave it if your control is on the other realisation.
...\Model\OSGB\Data is the OSGB copy of this mesh. Combining works on the OBJ tiles CoPre writes beside it: pick ...\Model\OBJ instead.	Job 3 was pointed at the OSGB copy of the mesh, most likely a folder remembered from version 0.1.1. Press Use Model\OBJ.
The .obj takes this folder's name, and rOrtho refuses a name with a space in it: an .obj reads a space in its texture file's name as two names. Pick a folder name without spaces.	Rename the folder out with a hyphen or an underscore instead of the space, for example AB-Framing-mesh.
This folder already has files in it. Pick an empty or new folder, or rOrtho will refuse to write over them.	Job 1's folder out is not empty. Despite the sentence, the button stays on. A run into this folder replaces files with the same names and deletes the images folder in it, with everything inside, before it writes its own. To keep what is there, press Choose... and pick an empty or new folder. After a finished run, rOrtho proposes rOrtho-photos-2 by itself.
The folder out is inside the folder in. Pick one beside it instead.	Combine mesh tiles will not run into this folder. Prep photos and Make an orthomosaic will, and write their files inside the export. Press Choose... under 2. Folder out and pick a folder beside it.
STOPPED - a check failed, nothing was written	One of Job 1's checks found a problem in the export. Press Open the report; it names the check and what to do about it.
DID NOT FINISH	The engine reported an error, which is shown under the headline with the last lines of the log. Try once more. If it fails the same way, press Copy details for support and paste the text into an email to iGage.
rOrtho is not registered on this computer. or The rOrtho trial ended on <date>.	Send this computer's ID to iGage and enter the code you get back. See Registration and trial.
Stop or finish the current job before closing rOrtho.	A job is running. Press Stop or let it finish, then close the window.