Skip to content

CLAUDE.md

Latest commit

 

History

History
128 lines (101 loc) · 4.84 KB

CLAUDE.md

File metadata and controls

128 lines (101 loc) · 4.84 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Python Syntax Checking

Always use the project script — never use python -c "import ast ...":

cd python/
python check_syntax.py PiFinder/file1.py PiFinder/file2.py

Development Commands

Development workflow uses Nox for task automation:

nox -s lint          # Code linting with Ruff (auto-fixes issues)
nox -s format        # Code formatting with Ruff
nox -s type_hints    # Type checking with MyPy
nox -s smoke_tests   # Quick functionality validation
nox -s unit_tests    # Full unit test suite
nox -s babel         # I18n message extraction and compilation

Direct testing with pytest:

pytest -m smoke      # Smoke tests for core functionality
pytest -m unit       # Unit tests for isolated components
pytest -m integration # End-to-end integration tests

Development setup:

cd python/
python3.9 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements_dev.txt

If the .venv dir already exists, you can directly source it and run the app.

Running the application: Development setup has to have run and you should be in .venv virtual environment

cd python/
python -m PiFinder.main [options]

Usual startup:

python3.9 -m PiFinder.main -fh --camera debug --keyboard local -x

Architecture Overview

Multi-Process Design: PiFinder uses a process-based architecture where each major subsystem runs in its own process, communicating via queues and shared state objects:

  • Main Process (main.py) - UI event loop, menu system, user interaction
  • Camera Process - Image capture from various camera types (Pi, ASI, debug)
  • Solver Process - Plate solving using Tetra3/Cedar libraries for star pattern recognition
  • GPS Process - Location/time via GPSD or UBlox direct interface
  • IMU Process - Motion tracking with BNO055 sensor
  • Integrator Process - Combines solver + IMU data for real-time positioning
  • Web Server Process - Web interface and SkySafari telescope control integration
  • Position Server Process - External protocol support

State Management:

  • SharedStateObj - Process-shared state using multiprocessing managers
  • UIState - UI-specific state management
  • Real-time synchronization of telescope position, GPS coordinates, and solved sky coordinates

Database Layer:

  • SQLite backend (astro_data/pifinder_objects.db)
  • ObjectsDatabase - Astronomical catalog management (NGC, Messier, etc.)
  • ObservationsDatabase - Session logging and observation tracking
  • Modular catalog import system supporting multiple astronomical databases

Hardware Abstraction:

  • Camera interface supporting IMX296 (global shutter), IMX290/462, HQ cameras
  • Display system for SSD1351 OLED and ST7789 LCD with red-light preservation
  • Hardware keypad with PWM brightness control
  • GPS integration via GPSD or direct UBlox protocol
  • IMU sensor integration for motion detection and telescope orientation

Key Directories

  • python/PiFinder/ - Core application modules
  • python/PiFinder/ui/ - User interface components (menus, screens, charts)
  • python/PiFinder/db/ - Database abstraction layer
  • astro_data/ - Astronomical catalogs and object databases
  • python/tests/ - Test suite (smoke, unit, integration markers)
  • case/ - 3D printable enclosure files
  • docs/ - Documentation and build guides

Configuration

Config Files:

  • default_config.json - System defaults
  • ~/PiFinder_data/config.json - User settings
  • Equipment profiles for telescopes and eyepieces
  • Display, camera, GPS, and solver parameters

Hardware Configuration:

  • Camera selection: Pi Camera, ASI cameras, debug mode
  • Display type: OLED vs LCD with brightness/orientation settings
  • Input method: hardware keypad, local keyboard, web interface
  • GPS receiver: GPSD daemon vs direct UBlox protocol

Testing Strategy

Tests use pytest with custom markers for different test types. The smoke tests provide quick validation while unit tests cover isolated functionality. Integration tests validate end-to-end workflows including the multi-process architecture.

Key test areas:

  • Calculation utilities and coordinate transformations
  • Catalog data validation and import processes
  • Menu structure and navigation logic
  • Multi-process logging and communication
  • Hardware interface abstractions

Code Quality

  • Linting: Ruff with Python 3.9 target, Black-compatible formatting
  • Type Checking: MyPy with gradual typing adoption
  • Code Style: 88-character line length, double quotes, space indentation
  • I18n Support: Babel integration for multi-language UI

The codebase follows modern Python practices with type hints, comprehensive testing, and automated code quality checks integrated into the development workflow.