magsurveypy 1.0.0__tar.gz

magsurveypy-1.0.0/BATCH_COMMAND_EXAMPLES.md

@@ -0,0 +1,77 @@
+# Workflow Cookbook
+
+These examples use the public acquisition-class interface.
+
+## Multichannel survey
+
+```bash
+mspy project init Rupea --category multichannel
+mspy project import Rupea /path/to/acquisition_export --type multichannel
+mspy survey multichannel --project Rupea --format auto --workflow standard
+mspy analyze survey --project Rupea
+mspy process interpolate --project Rupea
+```
+
+## Multichannel ploughed/noisy variants
+
+```bash
+mspy survey multichannel --project Site --format auto --workflow ploughed
+```
+
+```bash
+mspy survey multichannel --project Site --format auto --workflow noisy
+```
+
+## Total-field preservation workflow
+
+```bash
+mspy project init Site --category total-field
+mspy project import Site /path/to/data --type total-field
+mspy survey grid --project Site --protocol total-field --workflow preservation
+```
+
+## Total-field archaeology workflow
+
+```bash
+mspy survey grid --project Site --protocol total-field \
+  --traverse-zero median --deslope robust \
+  --destripe protected --destripe-strength 1 \
+  --high-pass 5 --archaeology-center robust \
+  --cell-size 0.25 --statistic mean
+```
+
+## Optional vertical gradient from split total-field sensors
+
+```bash
+mspy survey grid --project Site --protocol total-field \
+  --gradient vertical --sensor-separation 0.50
+```
+
+## Optional horizontal gradient from split total-field sensors
+
+```bash
+mspy survey grid --project Site --protocol total-field \
+  --gradient horizontal --sensor-separation 0.50
+```
+
+These gradient commands retain `Results/TOTAL_FIELD` and add `Results/GRADIENT_VERTICAL` or `Results/GRADIENT_HORIZONTAL`.
+
+## Fluxgate/gradiometer local grids
+
+```bash
+mspy project init GradSite --category fluxgate
+mspy project import GradSite /path/to/grid_data --type fluxgate
+mspy layout gui --project GradSite --protocol fluxgate
+mspy layout validate --project GradSite --protocol fluxgate
+mspy survey grid --project GradSite --protocol fluxgate --workflow archaeology
+```
+
+## Analysis and presentation
+
+```bash
+mspy analyze survey --project Site
+mspy analyze spectrum --project Site --from INTERPOLATED
+mspy figure single --project Site --from INTERPOLATED --display-range 15
+mspy export map --project Site --from INTERPOLATED
+mspy web --project Site
+```

magsurveypy-1.0.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use MagSurveyPy in research, please cite the software and the associated publication when available."
+title: "MagSurveyPy: Archaeological Magnetometry Prospection Suite"
+type: software
+license: BSD-3-Clause
+authors:
+  - family-names: "Hegyi"
+    given-names: "Alexandru"
+version: 1.0.0
+date-released: 2026-09-10
+url: "https://github.com/alexandruhegyi/MagSurveyPy"
+repository-code: "https://github.com/alexandruhegyi/MagSurveyPy"

magsurveypy-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing to MagSurveyPy
+
+Contributions are welcome through GitHub issues and pull requests.
+
+For code changes:
+
+1. Create a branch from the current development branch.
+2. Keep scientific changes separate from interface/documentation changes where possible.
+3. Add or update a regression test when changing processing behavior.
+4. Run `mspy --version`, `mspy --help`, and `mspy tools doctor` after installation.
+5. Describe any change that can alter scientific output explicitly in the pull request.
+
+Please avoid committing project datasets, generated results, environments, caches, or credentials.

magsurveypy-1.0.0/INSTALL.md

@@ -0,0 +1,162 @@
+# MagSurveyPy v1.0.0 — Installation
+
+MagSurveyPy supports Python 3.11 and newer. The installed command-line interface is `mspy`.
+
+## Recommended installation: pip
+
+### From PyPI
+
+After the public PyPI release:
+
+```bash
+python -m pip install magsurveypy
+```
+
+Verify:
+
+```bash
+mspy --version
+mspy --help
+mspy tools doctor
+```
+
+### From a cloned or extracted source tree
+
+From the directory containing `pyproject.toml`:
+
+```bash
+python -m pip install .
+```
+
+For development only:
+
+```bash
+python -m pip install -e .
+```
+
+To refresh an installed local checkout without reinstalling already-present dependencies:
+
+```bash
+python -m pip install --force-reinstall --no-deps .
+```
+
+The `[project.scripts]` entry in `pyproject.toml` creates `mspy` automatically. No shell launcher or manually created alias is required.
+
+### Install directly from GitHub
+
+After the public repository is ready:
+
+```bash
+python -m pip install git+https://github.com/alexandruhegyi/MagSurveyPy.git
+```
+
+### Upgrade
+
+```bash
+python -m pip install --upgrade magsurveypy
+```
+
+### Uninstall
+
+```bash
+python -m pip uninstall magsurveypy
+```
+
+If you installed into a virtual environment or Conda environment, activate that same environment before uninstalling. Uninstalling MagSurveyPy removes the installed package and `mspy` command from that environment only; it does not delete user projects, raw data, processed results, source folders or downloaded archives.
+
+## Alternative installation: Conda environment
+
+The supplied `environment.yml` is an alternative for users who prefer Conda/Miniforge. Run it from the MagSurveyPy source directory:
+
+```bash
+conda env create -f environment.yml
+conda activate magsurveypy
+mspy --version
+mspy --help
+```
+
+The environment file installs both the scientific/GIS dependencies and the local MagSurveyPy package. Therefore the `mspy` command is created inside the Conda environment as well.
+
+To remove the entire Conda environment:
+
+```bash
+conda deactivate
+conda env remove -n magsurveypy
+```
+
+To keep the environment but uninstall only MagSurveyPy:
+
+```bash
+conda activate magsurveypy
+python -m pip uninstall magsurveypy
+```
+
+## Project workspace
+
+Projects are stored by default under:
+
+```text
+~/MagSurveyPy_Projects/
+```
+
+Set a custom workspace with `MAGSURVEYPY_WORKSPACE`.
+
+Linux/macOS:
+
+```bash
+export MAGSURVEYPY_WORKSPACE=/data/MagSurveyPy_Projects
+```
+
+Windows PowerShell:
+
+```powershell
+$env:MAGSURVEYPY_WORKSPACE = "D:\MagSurveyPy_Projects"
+```
+
+## First project
+
+Multichannel:
+
+```bash
+mspy project init Site --category multichannel
+mspy project import Site /path/to/data --type multichannel
+mspy survey multichannel --project Site --format auto --workflow standard
+```
+
+Total field:
+
+```bash
+mspy project init Site --category total-field
+mspy project import Site /path/to/data --type total-field
+mspy survey grid --project Site --protocol total-field --workflow preservation
+```
+
+Fluxgate/gradiometer:
+
+```bash
+mspy project init Site --category fluxgate
+mspy project import Site /path/to/data --type fluxgate
+mspy survey grid --project Site --protocol fluxgate --workflow archaeology
+```
+
+For split-sensor total-field data, optional gradient products can be added with `--gradient vertical` or `--gradient horizontal` and a known `--sensor-separation`.
+
+## Linux Tk support
+
+The local-grid layout editor uses Tk. Most Conda distributions and standard Python installers provide it. On a minimal Debian/Ubuntu system, if Tk is unavailable:
+
+```bash
+sudo apt install python3-tk
+```
+
+## Troubleshooting
+
+Confirm which executable is active:
+
+```bash
+which mspy
+mspy --version
+python -m pip show magsurveypy
+```
+
+On Windows PowerShell use `Get-Command mspy` instead of `which mspy`.

magsurveypy-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Alexandru Hegyi
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

magsurveypy-1.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include INSTALL.md
+include BATCH_COMMAND_EXAMPLES.md
+recursive-include src/magsurveypy/assets *.png
+recursive-include src/magsurveypy/web *.html
+recursive-include docs *.md
+recursive-include examples *.sh *.ps1
+recursive-include templates *.csv
+
+include LICENSE
+include CITATION.cff
+include CONTRIBUTING.md
+include SECURITY.md

magsurveypy-1.0.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: magsurveypy
+Version: 1.0.0
+Summary: Archaeological Magnetometry Prospection Suite
+Author-email: Alexandru Hegyi <alexandruhegyi@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Alexandru Hegyi
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Homepage, https://alexandruhegyi.com
+Project-URL: Documentation, https://github.com/alexandruhegyi/MagSurveyPy
+Project-URL: Source, https://github.com/alexandruhegyi/MagSurveyPy
+Project-URL: Issues, https://github.com/alexandruhegyi/MagSurveyPy/issues
+Keywords: archaeology,archaeological geophysics,magnetometry,geophysics,GIS,magnetic prospection
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyproj>=3.6
+Requires-Dist: rasterio>=1.3
+Requires-Dist: affine>=2.4
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: tqdm>=4.66
+Requires-Dist: scikit-image>=0.22
+Requires-Dist: Pillow>=10
+Requires-Dist: geopandas>=0.14
+Requires-Dist: shapely>=2.0
+Requires-Dist: threadpoolctl>=3.1
+Requires-Dist: contextily>=1.5
+Requires-Dist: xyzservices>=2024.4.0
+Requires-Dist: metpy>=1.6
+Requires-Dist: ppigrf>=2.0.0
+Requires-Dist: pyogrio>=0.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# MagSurveyPy v1.0.0
+
+![MagSurveyPy](src/magsurveypy/assets/magsurveypy_logo.png)
+
+**Archaeological Magnetometry Prospection Suite**  
+Developed by **Alexandru Hegyi, PhD**  
+Website: https://alexandruhegyi.com · Email: alexandruhegyi@gmail.com · GitHub: https://github.com/alexandruhegyi
+
+MagSurveyPy is a project-based Python package and command-line application for archaeological magnetometry processing, quality control, analysis, visualization, GIS integration, cartographic export and local Web GIS. The public survey interface is organized around scientific acquisition classes rather than instrument manufacturers.
+
+## Survey model
+
+MagSurveyPy v1.0.0 uses two primary survey families:
+
+```text
+mspy survey multichannel ...
+mspy survey grid --protocol total-field ...
+mspy survey grid --protocol fluxgate ...
+```
+
+- **Multichannel**: multichannel magnetic acquisition, including supported native acquisition exports and normalized ASC/tabular data while retaining source, session, sensor and channel provenance where available.
+- **Total field**: gridded scalar total magnetic field data in nT. A normal exported file may contain one final reading column and is processed directly.
+- **Fluxgate**: gridded fluxgate magnetometry/gradiometry data, normally in nT/m.
+
+File formats are adapters, not survey categories. Supported workflows include PRM as one multichannel input example, paired HDR/DAT as one grid-format example, and generic ASC/CSV/TXT/XYZ/DAT and quantitative GIS raster/vector formats where scientifically meaningful.
+
+### Optional gradients from split-sensor total-field data
+
+If a total-field file retains two simultaneous sensor channels, MagSurveyPy can create an **additional** vertical or horizontal gradient product without replacing the original total-field result:
+
+```bash
+mspy survey grid --project Site --protocol total-field \
+  --gradient vertical --sensor-separation 0.50
+
+mspy survey grid --project Site --protocol total-field \
+  --gradient horizontal --sensor-separation 0.50
+```
+
+For vertical geometry, the default paired-sensor convention is sensor 1/top and sensor 2/bottom, with `(top - bottom) / separation`. For horizontal geometry, sensor 1/left and sensor 2/right are used, with `(right - left) / separation`. Column names and sign convention can be specified explicitly. If a measured gradient column already exists, it can be used directly. **Sensor separation is never guessed.**
+
+A file containing only one final reading column remains a standard total-field input; simply omit `--gradient`.
+
+## Installation
+
+### Recommended: pip
+
+When MagSurveyPy is available from PyPI:
+
+```bash
+python -m pip install magsurveypy
+```
+
+For the current source checkout:
+
+```bash
+python -m pip install .
+```
+
+Installation creates the `mspy` command automatically through the package entry point:
+
+```bash
+mspy --version
+mspy --help
+mspy tools doctor
+```
+
+Upgrade later with:
+
+```bash
+python -m pip install --upgrade magsurveypy
+```
+
+Uninstall with:
+
+```bash
+python -m pip uninstall magsurveypy
+```
+
+This removes the installed Python package and the `mspy` entry point from the active environment. It does **not** remove MagSurveyPy projects, raw survey data, processed results, source folders or downloaded archives.
+
+### Alternative: Conda environment
+
+From the repository root:
+
+```bash
+conda env create -f environment.yml
+conda activate magsurveypy
+mspy --version
+```
+
+The supplied Conda environment installs the MagSurveyPy package itself, so the same `mspy` command is available; no manual launcher or shell alias is required.
+
+See [INSTALL.md](INSTALL.md) for details.
+
+## Project creation
+
+Projects are stored by default under `~/MagSurveyPy_Projects/` and use generic acquisition folders:
+
+```text
+Site/
+├── project.json
+├── RawData/
+│   ├── Multichannel/
+│   ├── TotalField/
+│   ├── Fluxgate/
+│   ├── Generic/
+│   ├── GNSS/
+│   └── BaseStation/
+├── Config/
+├── Layouts/
+├── Results/
+├── Reports/
+├── Exports/
+├── Logs/
+└── Temp/
+```
+
+Create a project according to its main acquisition class:
+
+```bash
+mspy project init Rupea --category multichannel
+mspy project init Foeni --category total-field
+mspy project init GradSite --category fluxgate
+mspy project init MixedSite --category mixed
+```
+
+Import data into the corresponding generic branch:
+
+```bash
+mspy project import Rupea /path/to/data --type multichannel
+mspy project import Foeni /path/to/data --type total-field
+mspy project import GradSite /path/to/data --type fluxgate
+```
+
+`--mode link` can be used instead of copying files when appropriate.
+
+## Typical workflows
+
+### Multichannel magnetic acquisition
+
+```bash
+mspy project init Rupea --category multichannel
+mspy project import Rupea /path/to/multichannel_export --type multichannel
+mspy survey multichannel --project Rupea --format auto --workflow standard
+mspy analyze survey --project Rupea
+mspy process interpolate --project Rupea
+# Explicit source files may also be written as:
+mspy process interpolate --project Rupea --input ./points.asc --method archaeology
+mspy figure single --project Rupea --from INTERPOLATED --display-range 15
+```
+
+Normalized ASC can be supplied directly where the existing multichannel importer supports it. Format-specific adapters can be selected explicitly when automatic detection is not suitable.
+
+### Total-field grid
+
+```bash
+mspy project init Foeni --category total-field
+mspy project import Foeni /path/to/total_field_data --type total-field
+mspy survey grid --project Foeni --protocol total-field --workflow preservation
+mspy analyze survey --project Foeni --from TOTAL_FIELD
+```
+
+A more archaeology-oriented processing example is:
+
+```bash
+mspy survey grid --project Foeni --protocol total-field \
+  --traverse-zero median \
+  --deslope robust \
+  --destripe protected \
+  --destripe-strength 1 \
+  --high-pass 5 \
+  --archaeology-center median \
+  --cell-size 0.25 \
+  --statistic mean
+```
+
+The absolute/reference field is retained separately from derived archaeology-oriented products.
+
+### Fluxgate / gradiometer grid
+
+```bash
+mspy project init GradSite --category fluxgate
+mspy project import GradSite /path/to/grid_data --type fluxgate
+mspy layout gui --project GradSite --protocol fluxgate
+mspy layout validate --project GradSite --protocol fluxgate
+mspy survey grid --project GradSite --protocol fluxgate --workflow archaeology
+mspy analyze survey --project GradSite --from FLUXGATE
+```
+
+## Command groups
+
+```text
+project   create, import, configure and inspect projects
+survey    initial acquisition-aware processing
+layout    define and validate local-grid geometry
+process   interpolation, cleaning, enhancement and derived products
+filter    explicit observation/raster corrections
+analyze   survey, line, sensor, raster, spectrum and stage QC
+figure    scientific and publication figures
+export    GIS/cartographic outputs and reprojection
+web       interactive local Web GIS
+gnss      GNSS/RINEX/PPK utilities
+tools     diagnostics and generated help
+guide     scientific workflow guides
+help      detailed command help
+```
+
+Use `mspy --help`, `mspy project --help`, `mspy survey --help`, and `mspy survey grid --help` for built-in documentation.
+
+## Reproducibility and data preservation
+
+MagSurveyPy keeps original field files separate from derived products. Processing commands maintain project logs, and `--increment` can preserve an existing derived stage while creating a numbered output stage. Analysis commands create diagnostics without altering scientific data. Display-only controls such as brightness, contrast, gamma and saturation do not modify quantitative raster values.
+
+## License and warranty
+
+MagSurveyPy is distributed under the **BSD 3-Clause License**. The full legal terms are in [LICENSE](LICENSE).
+
+The software is provided **“AS IS”**, without warranties of any kind. Users remain responsible for validating processing choices, coordinate systems, sensor geometry, derived gradients, quantitative outputs and archaeological interpretation for their own data and purpose.
+
+## Citation
+
+Citation metadata are supplied in [CITATION.cff](CITATION.cff). A persistent DOI will be added after the v1.0.0 release is archived.