{
  "markdown": "# Flyvercity CLI Tools Suite (fvctools)\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)\n[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\n`fvctools` is a modular Python-based CLI suite designed for the processing, conversion, and validation of geospatial aviation data, including Flight Logs and Radar Logs. It serves as the backbone of Flyvercity's data pipeline, enabling seamless data integration and analysis across different platforms and formats.\n\n## Installation\n\n### Unix Shells (Linux, macOS, WSL)\n\n```bash\nsource scripts/Login-ToCodeArtifact.sh\n./scripts/Install-FvcTools.sh\n```\n\n### PowerShell\n\n```pwsh\n.\\scripts\\Login-ToCodeArtifact.ps1\n.\\scripts\\Install-FvcTools.ps1\n```\n\n## Core Toolsets\n\nThe `fvctools` suite is organized into specialized toolsets for data manipulation, geospatial calculations, and visualization.\n\n### Data File Tools (`fvc df`)\n\nThe `df` toolset manages the conversion, validation, and correlation of aviation data files into the unified Flyvercity (`.fvc`) format.\n\n- **Conversion**: Converts external formats (NMEA, ULog, DJI, etc.) to `.fvc`.\n  ```bash\n  uv run fvc df --in flight.nmea convert nmea flight.fvc\n  ```\n- **Validation**: Verifies that an `.fvc` file complies with the project's data schema.\n  ```bash\n  uv run fvc df --in flight.fvc validate\n  ```\n- **Correlation**: Synchronizes and merges multiple flight or radar log files.\n  ```bash\n  uv run fvc df correlate log1.fvc log2.fvc\n  ```\n\n### Geospatial Calculations (`fvc calc`)\n\nProvides utilities for precise coordinate and altitude calculations.\n\n- **Undulation**: Retrieves the EGM96 geoid undulation for a given latitude and longitude.\n  ```bash\n  uv run fvc calc undulation 52.3 4.9\n  ```\n- **Terrain**: Performs terrain elevation lookups using Digital Elevation Models (DEM).\n  ```bash\n  uv run fvc calc terrain 52.3 4.9 100.0\n  ```\n\n### Visualization (`fvc render`)\n\nGenerates interactive visualizations for flight data analysis.\n\n- **Interactive Maps (`fl`)**: Creates a standalone HTML visualization of flight paths.\n  ```bash\n  uv run fvc render fl flight.fvc --output ./map_results\n  ```\n\n## The Flyvercity Data Format (.fvc)\n\nThe `.fvc` format is the unified data standard used by all Flyvercity tools. It is a [JSON-Lines](https://jsonlines.org/) (`.jsonl`) formatted file where each line is a valid JSON object.\n\n### Structure\n\n1.  **Metadata Line**: The **first line** of every `.fvc` file must be a `METADATA` record. It contains essential information about the file's content and its origin.\n    - `content`: The type of data contained (e.g., `flightlog`, `radarlog`).\n    - `source`: The original format the data was converted from.\n    - `origin`: The name of the original source file or system.\n2.  **Data Records**: Subsequent lines contain individual data records (e.g., `FLIGHTLOG` or `RADARLOG` entries) that follow the schemas defined in the project.\n\n### Example\n\n```json\n{\"content\": \"flightlog\", \"source\": \"nmea\", \"origin\": \"flight_data_20231201.log\"}\n{\"time\": {\"unix\": 1756033206882}, \"pos\": {\"loc\": {\"lat\": 52.3, \"lon\": 4.9, \"alt\": 100.5}}}\n```\n\nFor detailed schema documentation of all record types, see [docs/schema/](docs/schema/README.md).\n\n## Supported External Formats\n\nFlyvercity CLI tools can convert data from a variety of external aviation and geospatial formats into the unified `.fvc` format.\n\n| Format Name | Description | Source Module |\n| :--- | :--- | :--- |\n| **AgentFly** | AgentFly simulator logs | `agentfly` |\n| **ART** | ART log format | `artlog` |\n| **Courageous** | Courageous project logs | `courageous` |\n| **CS Group** | CS Group logs | `csgroup` |\n| **DJI Datcon** | DJI Datcon logs | `datcon` |\n| **GeoJSON** | GeoJSON format | `geojson` |\n| **Gnettrack** | Gnettrack logs | `gnettrack` |\n| **NMEA** | NMEA GPS logs | `nmea` |\n| **Robin Radar** | Robin Radar XML | `robinradar` |\n| **Safir MQTT** | Safir MQTT logs | `safirmqtt` |\n| **Senhive** | Senhive logs | `senhive` |\n| **PX4 ULog** | PX4 ULog logs | `ulog` |\n\n### PowerShell Helper (`fvc shell`)\n\nFor Windows-based workflows, `fvctools` provides a PowerShell integration that treats CLI outputs as first-class objects, enabling advanced automation and scripting.\n\n1.  **Enable Integration**:\n    ```pwsh\n    Invoke-Expression (fvc shell pwsh)\n    ```\n2.  **Object-Oriented Usage**:\n    Outputs are automatically parsed into PowerShell objects for easy property access:\n    ```pwsh\n    # Access the undulation value directly from the command output\n    $height = (FvcTool calc undulation 52.3 4.9).undulation\n    ```\n\n## Development\n\nWe welcome contributions to `fvctools`! Follow these guidelines to get started.\n\n### Adding a New Format\n\nTo add support for a new data format, create a new module in `src/fvc/tools/df/xformats/`.\n\n#### Required Implementation\n\nEach format module must implement the `convert_to_fvc` function:\n\n```python\ndef convert_to_fvc(params, metadata, input_path, output):\n    \"\"\"\n    Args:\n        params (dict): CLI parameters and custom options.\n        metadata (dict): Metadata to be written as the first line.\n        input_path (Path): Path to the source file.\n        output (JsonlinesIO): Unified IO handler for writing .fvc records.\n    \"\"\"\n    # Implementation here\n    ...\n```\n\n### Testing\n\nTests are located in the `tests/` directory. Use `pytest` to run the suite:\n\n```bash\nuv run pytest\n```\n\n### Linting & Formatting\n\nWe use `ruff` to ensure code quality and consistent formatting.\n\n- **Check**:\n  ```bash\n  uv run ruff check .\n  ```\n- **Format**:\n  ```bash\n  uv run ruff format .\n  ```\n\n## For Developers\n\nThe project uses [uv](https://github.com/astral-sh/uv) for dependency management and environment isolation.\n\n1.  **Install dependencies**:\n    ```bash\n    uv sync\n    ```\n2.  **Verify installation**:\n    ```bash\n    uv run fvc --help\n    ```\n\n### For Windows/PowerShell Users\n\nA specialized installation script is provided for Windows environments to set up the CLI tools locally.\n\n1.  **Install**:\n    Run the provided installation script:\n    ```pwsh\n    .\\scripts\\Install-FvcTools.ps1\n    ```\n2.  **Load into session**:\n    To load the tools into your current PowerShell session, source the loader script:\n    ```pwsh\n    . .\\pwsh\\Load-FvcTools.ps1\n    ```\n\n### For Linux/macOS Users (Bash)\n\nEquivalent Bash scripts are provided for Linux and macOS environments.\n\n1.  **Authenticate**:\n    Fetch the CodeArtifact token and set environment variables:\n    ```bash\n    source scripts/Login-ToCodeArtifact.sh\n    ```\n2.  **Install**:\n    Run the installation script:\n    ```bash\n    ./scripts/Install-FvcTools.sh\n    ```\n",
  "bytes": 6899,
  "sha": "bface58a48b3fab36de74cce382010dac3a882d2c94b6c7847ae36b3880164b9",
  "repo_slug": "flyvercity/fvctools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_flyvercity_fvctools_openwiki_index_md_cd649347/readme"
}