USGSCSM

NPM Package: @usgs-astrogeology/usgscsm

CDN Links:

• jsDelivr: https://cdn.jsdelivr.net/npm/@usgs-astrogeology/usgscsm/dist/usgscsm.js
• unpkg: https://unpkg.com/@usgs-astrogeology/usgscsm/dist/usgscsm.js

This library provides Community Sensor Model (CSM)-compliant sensor models created by the USGS Astrogeology Science Center.

USGSCSM contains three different sensor models. The first is a generic framing camera model written from scratch. The second is a generic line scan camera model based on code from BAE Systems Information and Electronic Systems Integration, Inc. The third is a generic synthetic-aperture radar (SAR) sensor model.

Using USGSCSM

This library is a CSM plugin library that is intended to be dynamically loaded at run-time alongside the CSM API library.

Once the library is loaded, it can be accessed through the CSM plugin interface. For an example of how to do through the CSM C++ interface see the SensorModelFactory class in SensorUtils. For an example of how to do this through the CSM Python bindings see this notebook.

From the CSM plugin interface, a generic framing camera model (USGS_ASTRO_FRAME_SENSOR_MODEL), line scan camera model (USGS_ASTRO_LINE_SCANNER_SENSOR_MODEL), or a SAR model (USGS_ASTRO_SAR_SENSOR_MODEL) can be instantiated from a suitable Image Support Data (ISD) file.

Camera model format and model state

Under the CSM standard, each plugin library can define its own ISD camera model format. This library uses an auxiliary JSON formatted file that must be next to the image file passed to the CSM::ISD class. ISD files and strings can be generated by using ALE with metakernels and accompanying SPICE kernels, or from ISIS cubes that have attached SPICE data.

The camera model read from an ISD file is converted at load time to an internal representation which makes camera operations more efficient. This optimized model state can be saved to disk as a JSON-formatted file, be used interchangeably with the original ISD model, and also shared among various photogrammetric packages.

The model state can also be saved in binary msgpack format, which is smaller and much faster to load than JSON. The .isd extension is suggested for binary model state files but is not enforced. When loading, the format is determined by inspecting the first bytes of the file.

The camera model state can be modified by an application of a rotation and translation, which is necessary in order to refine a camera's position and orientation in photogrammetry, while these operations are not easy to express in the original ISD format.

The GXP .sup file format is also supported for interoperability with the GXP software suite.

This library provides functionality for saving the model state file, as discussed in the next section.

Camera model processing

USGSCSM ships with a program named usgscsm_cam_test, which is able to load a CSM camera model, whether in the original ISD format, its model state representation, or binary msgpack model state, export the model state in JSON or binary format, and perform basic camera operations, as described in its documentation.

Enabling logging

Logging of the internal operations in the sensor models can be enabled by setting the USGSCSM_LOG_FILE environment variable to the file the log should be written to. To have the logging information printed to the standard output or standard error, set this to stdout or stderr.

You can adjust how much information is logged by setting the USGSCSM_LOG_LEVEL environment variable. The log level is not case sensitive. The log levels are:

Level	Description
trace	Intermediate calculation values
debug	All function calls and returns
info	Only core photogrammetry calls and returns - Default log level
warn	CSM warnings
err	CSM exceptions
critical	Critical errors
off	No log messages

All log messages of level USGSCSM_LOG_LEVEL and below will be logged. For example, setting the log level to info will log all messages of types info, warn, err, critical, and off. Note that these logs can become several GB in size when the log level is set to debug or trace.

---

Build requirements

• cmake 3.15 or newer
• GNU-compatible Make
• a C++11 compliant compiler
• JSON, ALE, and PROJ (internal or external)
• CSM

Internal Dependencies (git submodules)

JSON, ALE, and PROJ must be built-in for the release, so they are included as git submodules. gtest is also included as a git submodule for development.

To clone the submodules as well when cloning, add the --recurse-submodules flag:
git clone --recurse-submodules <repo link>

Or, after cloning, run:
git submodule update --init --recursive

External Dependencies (conda)

The rest of the dependencies (or, if not testing/building for release, all of the dependencies) are listed in the environment.yml and can be installed with conda:

conda env create -n usgscsm -f environment.yml

Building USGSCSM

USGSCSM uses a standard cmake build system. To compile the library and tests use the following commands:

1. mkdir build && cd build
2. cmake -DUSGSCSM_EXTERNAL_DEPS=OFF -DUSGSCSM_BUILD_DOCS=OFF .. && cmake --build .

If you are using external dependencies via Conda or system level installations add the -DUSGSCSM_EXTERNAL_DEPS=ON flag to the cmake command.

You can also disable the tests and the googletest dependency by adding the -DUSGSCSM_BUILD_TESTS=OFF flag to the cmake command.

Testing USGSCSM

All of the tests for USGSCSM are written in the googletest framework and are run via ctest. To run all of the tests simply run ctest in the build.

All of the tests are purposefully written to use generic data that values have been hand validated. This data can be found under tests/data.

Code style

This software package uses a modified form of the Google C++ Style Guide.

Here are some exceptions:

1. Non-const pass-by-reference is allowed.
2. No copyright notice is necessary
3. Static/global string constants are allowed to be std::strings, rather than C-style strings

To attempt to automatically format any new code to this style, run: clang-format -style=Google -i file.cpp For more information see: ClangFormat

To check for compliance, run: cpplint file.cpp and ignore errors in the list of exclusions above. For more information, see: cpplint.

WebAssembly Usage

See Astro Software Docs for more details and examples.

USGSCSM can be compiled to WebAssembly for use in web browsers and Node.js.

Option 1: Import from jsDelivr CDN

<script type="module">

  // Import from jsDelivr CDN
  import USGSCSM from 'https://cdn.jsdelivr.net/npm/@usgs-astrogeology/usgscsm/dist/usgscsm.js';
  
  const Module = await USGSCSM();
  const model = new Module.USGSCSMModel();
  
  // Fetch an ISD JSON and Load camera model from it
  // Try swapping out the URL with your own ISD JSON's URL
  const isdJson = await fetch('https://cdn.jsdelivr.net/gh/DOI-USGS/usgscsm/tests/data/simpleFramerISD.json').then(r => r.text());
  model.loadFromISD(isdJson, 'USGS_ASTRO_FRAME_SENSOR_MODEL');
  
  // Transform coordinates
  const ground = model.imageToGround(512, 1024, 0);
  console.log(`Ground: (${ground.x}, ${ground.y}, ${ground.z})`);
</script>

Option 2: Installing with NPM

# In your terminal in the project folder:
npm install @usgs-astrogeology/usgscsm

Then import in your javascript like this:

import usgscsm from "@usgs-astrogeology/usgscsm/"

You'll need a Module Bundler, like Vite. The rest is the same as above.

Option 3: Manually Download

Or download files from GitHub Releases:

• usgscsm.js - JavaScript module
• usgscsm.wasm - WebAssembly binary
• usgscsm.d.ts - TypeScript definitions

Note: The WASM file (usgscsm.wasm) must be in the same directory as the JS file.

⚠️ You need a Server

Accessing a page with USGSCSM via file:// won't work. Webassembly execution requires running a server:

# If you used `npm create vite@latest` for your Module Bundler:
npm run dev

# OR

# Python Server
python3 -m http.server 8080

Building for WebAssembly

Requirements:

• Emscripten 3.1.58 (compatible with Binaryen 117)
• cmake 3.15+

Build:

# Clone with submodules
git clone --recurse-submodules https://github.com/USGS-Astrogeology/usgscsm.git
cd usgscsm

# Create the usgscsm Conda Env and install Emscripten
conda env create -n usgscsm -f environment.yml
conda activate usgscsm
conda install -c conda-forge emscripten=3.1.58

# Configure and build
mkdir wasmbuild && cd wasmbuild
emcmake cmake ..
emmake make

# Output files are in wasmbuild/dist/
ls -lh dist/

Output files (in wasmbuild/dist/):

• usgscsm.js - JavaScript glue code (~123 KB, 30 KB gzipped)
• usgscsm.wasm - WebAssembly binary (~911 KB, 254 KB gzipped)
• usgscsm.d.ts - TypeScript definitions

Advanced Build Options:

# Debug build with source maps
emcmake cmake .. -DUSGSCSM_WASM_DEBUG=ON

# Disable optimization (faster build, larger binary)
emcmake cmake .. -DUSGSCSM_WASM_OPTIMIZE=OFF

# Build with tests (requires googletest)
emcmake cmake .. -DUSGSCSM_BUILD_TESTS=ON

Testing:

npm test

Browser Usage

// Using npm package
import USGSCSM from '@usgs-astrogeology/usgscsm';

// OR using CDN
// import USGSCSM from 'https://cdn.jsdelivr.net/npm/@usgs-astrogeology/usgscsm/dist/usgscsm.js';

const Module = await USGSCSM();
const model = new Module.USGSCSMModel();

// Load from ISD
const isdJson = await fetch('model.json').then(r => r.text());
model.loadFromISD(isdJson, 'USGS_ASTRO_FRAME_SENSOR_MODEL');

// Transform coordinates
const ground = model.imageToGround(100, 200, 0);
const pixel = model.groundToImage(ground.x, ground.y, ground.z);

Saving and Loading Model State

Camera models can be serialized to JSON state strings and restored later, enabling:

• Caching computed models for faster subsequent loads
• Sharing camera models between applications
• Storing refined camera parameters after bundle adjustment

import USGSCSM from './dist/usgscsm.js';

const Module = await USGSCSM();

// Load from ISD (slow - computes ephemeris)
const model1 = new Module.USGSCSMModel();
model1.loadFromISD(isdJson, 'USGS_ASTRO_FRAME_SENSOR_MODEL');

// Save model state for reuse
const state = model1.getModelState();
localStorage.setItem('cameraModel', state); // or send to server

// Later: Load from state (fast - precomputed)
const savedState = localStorage.getItem('cameraModel');
const model2 = new Module.USGSCSMModel();
model2.loadFromState(savedState);

// model2 produces identical results to model1
const ground = model2.imageToGround(100, 200, 0);

WASM Supported Models

• Frame cameras (USGS_ASTRO_FRAME_SENSOR_MODEL)
• Line scanners (USGS_ASTRO_LINE_SCANNER_SENSOR_MODEL)
• Push frame cameras (USGS_ASTRO_PUSH_FRAME_SENSOR_MODEL)
• SAR sensors (USGS_ASTRO_SAR_SENSOR_MODEL)