Crate compass_data

Expand description

§Compass Data

A Rust library for reading, writing, and working with Compass cave survey project files (.mak) and survey data files (.dat).

§Overview

This library enables interoperation and data sharing between cave survey software by providing a complete implementation of the Compass file formats. It supports:

Project files (.mak): Parse and create project files that organize multiple survey data files
Survey data files (.dat): Parse and serialize individual survey data with shots, stations, and metadata
Coordinate systems: UTM coordinates with support for 23 geodetic datums
Rich error reporting: Detailed error messages with source locations using miette

§Usage

§Reading a Project File

use compass_data::Project;
use std::path::PathBuf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Read a project file (parses metadata but doesn't load survey data yet)
    let project = Project::read(&PathBuf::from("cave.mak"))?;

    println!("Project has {} survey files", project.survey_files.len());

    // Access file metadata without loading survey data
    for dat_file in &project.survey_files {
        println!("  File: {}", dat_file.file_path.display());
        println!("  Datum: {:?}", dat_file.file_state.datum);
    }

    // Load all survey data from disk
    let loaded_project = project.load_survey_files()?;

    // Now access the actual survey data
    for dat_file in &loaded_project.survey_files {
        for survey in dat_file.surveys() {
            println!("Survey: {} - {} shots", survey.name, survey.shots.len());
        }
    }
    Ok(())
}

§Reading a Survey Data File Directly

use compass_data::Survey;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let contents = std::fs::read_to_string("survey.dat")?;
    let surveys = Survey::parse_dat_file(&contents)?;

    for survey in &surveys {
        println!("Cave: {}", survey.cave_name);
        println!("Survey: {}", survey.name);
        println!("Date: {}", survey.date);
        println!("Shots: {}", survey.shots.len());
    }
    Ok(())
}

§Serializing Survey Data

use compass_data::Survey;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse and re-serialize (round-trip)
    let contents = std::fs::read_to_string("survey.dat")?;
    let surveys = Survey::parse_dat_file(&contents)?;

    for survey in &surveys {
        let serialized = survey.serialize();
        std::fs::write(format!("{}.dat", survey.name), serialized)?;
    }
    Ok(())
}

§Key Types

Type	Description
`Project`	A Compass project file containing references to survey data files
`DatFile`	A survey data file reference with its associated state
`Survey`	A single survey containing shots, team info, date, and parameters
`Shot`	A single survey shot with distance, azimuth, inclination, and LRUD
`Datum`	Geodetic datum (NAD27, NAD83, WGS84, etc.)
`FileState`	Rolling state captured when a file is encountered during parsing

§Features

serde: Enable serialization/deserialization with serde
cli: Build the compass CLI tool for inspecting project and survey files

§CLI Tool

When built with the cli feature, a command-line tool is available:

# Install
cargo install compass_data --features cli

# Inspect a project file
compass inspect project cave.mak

# Inspect with full survey data
compass inspect project cave.mak --load

# Inspect a survey data file
compass inspect survey cave.dat

# Show detailed shot data
compass inspect survey cave.dat --verbose

§File Format Documentation

The Compass file formats are documented at:

§License

Licensed under either:

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs§

BackSightCorrectionFactors
CorrectionFactors
DatFile: A survey data file (.dat) referenced by a project
EastNorthElevation: East North Elevation coordinates Always stored in meters
FileConvergence: UTM Convergence parameter from the % or * parameter in MAK files
FileState: State captured when a .dat file is encountered during project parsing.
Loaded: Marker type for survey and project files which have been fully loaded
Project: A Compass project file (.mak)
ProjectParameters: Project-level parameter flags from the ! parameter in MAK files
Shot
Survey
SurveyParameters
Unloaded: Marker type for survey and project files which have not been fully loaded yet
UtmLocation

Enums§

Datum: Compass projects can be defined in a variety of geodetic datums.
DeclinationMode: Declination mode for project-level declination handling
Error