Installation

System Requirements

Planet Ruler requires Python 3.8 or higher and supports the following platforms:

Linux: Ubuntu 18.04+, CentOS 7+, other modern distributions
macOS: 10.15+ (Catalina and newer)
Windows: 10+ with Python 3.8+

Python Dependencies

Core dependencies include:

NumPy ≥1.20.0: Numerical computing
SciPy ≥1.7.0: Scientific computing and optimization
Matplotlib ≥3.5.0: Plotting and visualization
Pandas ≥1.3.0: Data manipulation
Pillow ≥8.0.0: Image loading and processing
PyYAML ≥5.4.0: Configuration file parsing
tqdm ≥4.60.0: Progress bars
Tkinter: GUI toolkit for manual annotation (usually included with Python)

Optional dependencies for advanced features:

Segment Anything ≥1.0 (Python 3.8+): AI-powered automatic segmentation (alternative to manual annotation)
PyTorch ≥1.11.0: Required for Segment Anything
Seaborn ≥0.11.0: Statistical plotting
IPython ≥7.16.0: Interactive computing (for notebooks)

Installation Methods

From PyPI (Recommended)

python -m pip install planet_ruler

Optional: For AI segmentation support:

python -m pip install planet_ruler[ml]

From Source

git clone https://github.com/bogsdarking/planet_ruler.git
cd planet_ruler
python -m pip install -e .

For development with testing dependencies:

git clone https://github.com/bogsdarking/planet_ruler.git
cd planet_ruler
python -m pip install -e ".[dev]"

Using Conda (Development)

# Note: Not yet available on conda-forge, install from source:
git clone https://github.com/bogsdarking/planet_ruler.git
cd planet_ruler
conda install numpy scipy matplotlib pandas pillow pyyaml tqdm seaborn
pip install -e .

Virtual Environment Setup

We recommend using a virtual environment:

Using venv:

python -m venv planet-ruler-env
source planet-ruler-env/bin/activate  # On Windows: planet-ruler-env\Scripts\activate
python -m pip install planet_ruler

Using conda:

conda create -n planet-ruler python=3.9
conda activate planet-ruler
python -m pip install planet_ruler

Verification

Test your installation:

import planet_ruler.geometry as geom
import planet_ruler.observation as obs

# Test basic geometry function
horizon_dist = geom.horizon_distance(r=6371000, h=400000)
print(f"ISS horizon distance: {horizon_dist/1000:.1f} km")

# Should output: ISS horizon distance: 2290.7 km

Troubleshooting

Common Installation Issues

ImportError: No module named ‘torch’

The Segment Anything model requires PyTorch. Install with:

python -m pip install torch torchvision

PIL/Pillow conflicts

If you encounter PIL import errors:

python -m pip uninstall PIL Pillow
python -m pip install Pillow

NumPy/SciPy build errors

On some systems, you may need system-level dependencies:

Ubuntu/Debian:

sudo apt-get install python3-dev libopenblas-dev

macOS:

brew install openblas

Windows:

Install Microsoft Visual C++ Build Tools or use pre-compiled wheels via pip.

Performance Optimization

For improved performance, especially with large images:

Use conda-forge NumPy/SciPy (often includes optimized BLAS):
```
conda install -c conda-forge numpy scipy
```
Install OpenMP support for multi-threading:
```
conda install -c conda-forge openmp
```
Use SSD storage for faster image I/O operations

GPU Support

While Planet Ruler primarily uses CPU computations, GPU acceleration is available for:

Segment Anything model: Requires CUDA-capable GPU and PyTorch with CUDA support
Large-scale batch processing: Use PyTorch DataLoader with GPU tensors

To enable GPU support:

# Install PyTorch with CUDA support
python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

Next Steps

Review the Tutorials for guided examples
Explore Examples with real planetary data
Check the API Reference reference for detailed function documentation