Skip to content

Pro3DTool.md

Latest commit

 

History

History
125 lines (95 loc) · 5.15 KB

Pro3DTool.md

File metadata and controls

125 lines (95 loc) · 5.15 KB
Raw

pro3d-tool

pro3d-tool is PRo3D's command line companion. It is published as a dotnet tool and is independent of the PRo3D viewer application — nothing here requires the viewer to be installed.

It supersedes the older opc-tool (see Migrating).

Verbs

Verb What it does Documentation
kdtree Validate OPC directories and generate KdTrees Pro3DTool-KdTree.md
sun-angles Per-pixel illumination geometry for instrument images, for photometric work such as image calibration Pro3DTool-SunAngles.md
unproject Image pixel coordinates to body-fixed surface coordinates on a shape model Pro3DTool-Unproject.md
simulate-image Simulated instrument image of a body at a SPICE time: Lommel-Seeliger sun lighting, procedural micro-structure, cast shadows, optional de-shaded texture albedo Pro3DTool-SimulateImage.md
sample-layers Assemble AFC, ASPECT and HyperScout observations onto a body: per OPC vertex, which image sees it, where, under which sun geometry, and every band's value — as CSV keyed by vertex id Pro3DTool-SampleLayers.md

Install

dotnet tool install PRo3D.Tool --global

This needs the .NET 9 SDK. For a step-by-step setup on Windows, macOS and Linux — .NET, PATH, test data and SPICE kernels, with screenshots — see Installation.md.

> pro3d-tool

.--. .--.     .--. .--.
|   )|   )        )|   :
|--' |--' .-.  --: |   |
|    |  \(   )    )|   ;
'    '   ``-' `--' '--'   pro3d-tool by pro3d-space.

Command line tools for PRo3D data.

  kdtree          validate OPC directories and generate KdTrees
  sun-angles      render per-pixel illumination geometry for instrument images
  unproject       convert image pixel coordinates to body-fixed surface coordinates
  simulate-image  render a simulated instrument image of a body at a SPICE time
  sample-layers   assemble instrument images onto the OPC vertices of a body, as CSV

Run `pro3d-tool <verb> --help` for the options of a verb.

Each verb documents itself:

pro3d-tool kdtree --help
pro3d-tool sun-angles --help
pro3d-tool unproject --help
pro3d-tool simulate-image --help
pro3d-tool sample-layers --help

Test data

The examples on the verb pages run against public test data, which lives in its own repository so that a plain PRo3D clone stays small. Clone it anywhere and pass the path:

git clone https://github.com/pro3d-space/PRo3D.Resources.TestData.git

It contains an MSL/Stimson OPC surface, and under HERA/ a Didymos OPC together with an ASPECT instrument image and its metadata sidecars.

One runnable script per verb ships in the PRo3D source tree, in Windows and POSIX variants. They invoke the tool via dotnet run, so they work in a checkout before anything is published to NuGet:

scripts\run-kdtree.cmd          <path-to-clone>
scripts\run-sun-angles.cmd      <path-to-clone>
scripts\run-unproject.cmd       <path-to-clone>
scripts\run-simulate-image.cmd  <path-to-clone>

scripts/run-kdtree.sh           <path-to-clone>
scripts/run-sun-angles.sh       <path-to-clone>
scripts/run-unproject.sh        <path-to-clone>
scripts/run-simulate-image.sh   <path-to-clone>

SPICE kernels

Anything involving planetary geometry — body positions, orientations, the direction to the Sun — needs SPICE kernels. For Mars missions the kernels PRo3D needs are included. For HERA, make sure you have the appropriate kernels for your task; they are not part of the PRo3D test data. Download them from ESA's SPICE for HERA page — its Direct Download is a ZIP of the latest operational kernels (step by step with screenshots: Installation.md).

Then set PRO3D_SPICE_KERNELS to the unpacked HERA folder, or to its kernels subdirectory — either works:

setx PRO3D_SPICE_KERNELS C:\path\to\HERA        REM Windows
export PRO3D_SPICE_KERNELS=/path/to/HERA        #   POSIX

--kernel-root <dir> overrides the variable for a single run. There is deliberately no implicit default: with neither the flag nor the variable set, a verb that needs kernels fails rather than quietly using some other tree, because output computed from unintended kernels looks perfectly valid.

Migrating from opc-tool

opc-tool is deprecated. Its functionality is the kdtree verb, with the same option names, so migrating means prepending the verb:

opc-tool           --forcekdtreerebuild "F:\pro3d\data\dimorphos"   # old
pro3d-tool kdtree  --forcekdtreerebuild "F:\pro3d\data\dimorphos"   # new

One behavioural fix came with the move: in opc-tool, patch validation ran only when --skippatchvalidation was passed, and --generatedds never actually produced DDS files because the conversion was skipped whenever it was requested. Both now behave as documented. If you previously worked around this, the workaround is no longer needed.