Installation

Requirements

Python 3.9 or newer. Every dependency is installed automatically; none is optional in practice, which is why they are all base dependencies rather than extras.

Package	What needs it
`numpy`	Everything.
`numba`	The arrival scan is a compiled parallel kernel. Without it the profile walk falls back to interpreted Python and a real DEM becomes unusable.
`scipy`	Morphology and connected-component labelling.
`tifffile`	Reads and writes the GeoTIFF DEMs and mask rasters.
`imagecodecs`	Not imported by name anywhere, and required anyway: the DEMs are LZW-compressed and `tifffile` delegates that codec to it. Omitting it produces a decode failure that is hard to trace back to a missing package.
`matplotlib`	The overview maps; the KML contours are extracted from its paths.
`tqdm`	Progress bars over the tiled passes.

From PyPI

pip install oroscope

From a clone

Preferred if you want the notebooks, the example configurations, the benchmark harness or the test suite, none of which ship in the wheel:

git clone https://github.com/mbustama/oroscope.git
cd oroscope
pip install -e .

Optional extras

pip install -e '.[test]'        # pytest and coverage
pip install -e '.[docs]'        # everything `cd docs && make html` needs
pip install -e '.[notebooks]'   # enough to execute notebooks/ unaided
pip install -e '.[diagnostics]' # psutil, for RAM reporting during a run

Getting a DEM

A search needs a digital elevation model in GeoTIFF form, at roughly 30 m resolution. OpenTopography serves SRTM and ALOS AW3D30, both of which work.

oroscope-fetch-dem --open_topography_api_key YOUR_KEY

downloads the tiles for the bundled regions and writes matching configuration files. For anywhere else, download the tiles yourself, merge them if the region spans several, and cut the window you want:

oroscope-crop big.tif colca.tif --north -15.30 --south -15.85 \
    --west -72.40 --east -71.55

which prints the origin_lat and origin_lon to paste into a configuration.

Note

Two searches can only be combined if they cover identical ground at the same downsample_factor. oroscope-combine checks the world files and refuses rather than resampling, because two runs on differently-cropped DEMs would silently compare the wrong terrain.

Verifying the install

python -c "import arrival_scan, physics, scoring; print('ok')"
cd tests && python -m unittest discover

The suite is standard-library unittest and needs nothing beyond the package. Tests that need a real DEM skip automatically when input/dem/ is absent.