Installation ============ This page walks you through setting up Spatial-VTK in a conda environment, installing the package, and running a few quick checks before you start a workflow. You will need Python 3.10 through 3.13 and conda. If you are new to conda, the `conda getting started guide `__ is a good place to start. Create the Conda Environment ---------------------------- The public repository includes an environment file named ``svtk_environment.yaml`` at the repository root. Download that file from the `Spatial-VTK GitHub repository `__, or use the copy that is already present if you cloned the repository. From the directory that contains ``svtk_environment.yaml``, run: .. code-block:: bash conda env create -f svtk_environment.yaml conda activate spatial-vtk If you already created the environment and want to refresh it after the environment file changes, run: .. code-block:: bash conda env update -f svtk_environment.yaml --prune conda activate spatial-vtk Install from PyPI ----------------- This is the simplest route. It installs the base package, the public Python source modules, the ``svtk`` command, and the dashboard dependencies. .. code-block:: bash python -m pip install spatial-vtk The tutorial notebooks and example data are repository/docs-site assets, not part of the PyPI wheel. .. raw:: html
Advanced: install development extras

Use this only if you want to run the public test suite, build the docs, or validate a release from a source checkout. 

python -m pip install "spatial-vtk[dashboard,docs,notebooks,validation,waveforms]"

From a source checkout, use the editable form: 

python -m pip install -e ".[dashboard,docs,notebooks,validation,waveforms]"

After installing the validation extras, you can run: 

python -m pytest
Install from Source ------------------- Use this route when you want the repository files too, including docs, tutorial notebooks, example data, tests, and editable source code. .. code-block:: bash git clone https://github.com/bcbirkel/spatial-vtk.git cd spatial-vtk conda env create -f svtk_environment.yaml conda activate spatial-vtk python -m pip install -e ".[notebooks,waveforms]" If you are adding the package to an existing conda environment for interactive notebook work, include the notebook extra and register the kernel: .. code-block:: bash python -m pip install -e ".[notebooks,waveforms]" python -m ipykernel install --user --name spatial-vtk --display-name "spatial-vtk" The editable install means changes in the source checkout are picked up by the environment immediately. That is the most convenient setup while you are working through the tutorial notebooks or developing new analysis code. Check the Install ----------------- Run these checks from the same activated environment: .. code-block:: bash python -c "import spatial_vtk; print(spatial_vtk.__version__)" svtk --help If you installed from a source checkout and installed the advanced validation extras, you can also run the public test suite: .. code-block:: bash python -m pytest You are ready to continue once the import prints a version, ``svtk --help`` shows the command groups, and the tests pass if you chose to run them. Common Setup Notes ------------------ If conda cannot solve the environment, make sure you are using the ``conda-forge`` channel from ``svtk_environment.yaml``. Creating a fresh environment is usually cleaner than trying to reuse an older research environment with many unrelated packages. If map figures render without a basemap, check your network connection. Spatial-VTK uses ``contextily`` for basemap tiles, so basemap-backed maps need network access unless you already have the required tiles cached locally.