Metadata-Version: 2.4
Name: GSEGUtils
Version: 0.5.2
Summary: General utility functions and classes for GSEG research/projects
Author-email: Nicholas Meyer <meyernic@ethz.ch>, Jon Allemand <jonal@ethz.ch>
Maintainer-email: Nicholas Meyer <meyernic@ethz.ch>
License: BSD 3-Clause License
        
        Copyright (c) 2022–2026 ETH Zurich
        Department of Civil, Environmental and Geomatic Engineering (D-BAUG)
        Institute of Geodesy and Photogrammetry
        Geosensors and Engineering Geodesy
        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 Nicholas Meyer & Jon Allemand, Geosensors and
           Engineering Geodesy, Institute of Geodesy and Photogrammetry, ETH Zurich,
           Switzerland, 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: Documentation, https://gsegutils.readthedocs.io/en/stable/
Project-URL: Repository, https://github.com/gseg-ethz/GSEGUtils.git
Project-URL: Issues, https://github.com/gseg-ethz/GSEGUtils/issues
Project-URL: Changelog, https://github.com/gseg-ethz/GSEGUtils/blob/main/CHANGELOG.md
Keywords: ONE,TWO
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Framework :: Pydantic
Classifier: License :: OSI Approved :: BSD License
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.4,>=2.0
Requires-Dist: pydantic~=2.11
Requires-Dist: numpydantic~=1.10
Requires-Dist: psutil~=7.0
Provides-Extra: doc
Requires-Dist: sphinx~=8.2; extra == "doc"
Requires-Dist: sphinx_rtd_theme; extra == "doc"
Provides-Extra: dev
Requires-Dist: ruff~=0.15; extra == "dev"
Requires-Dist: mypy~=1.17; extra == "dev"
Requires-Dist: pyright~=1.1; extra == "dev"
Requires-Dist: pre-commit~=4.3; extra == "dev"
Requires-Dist: pytest~=8.4; extra == "dev"
Requires-Dist: pytest-cov~=5.0; extra == "dev"
Requires-Dist: coverage~=7.0; extra == "dev"
Requires-Dist: pytest-benchmark~=5.2; extra == "dev"
Dynamic: license-file

# GSEGUtils

[![License: BSD-3](https://img.shields.io/badge/License-BSD_3-yellow.svg)](LICENSE)
[![Documentation Status](https://readthedocs.org/projects/gsegutils/badge/)](https://gsegutils.readthedocs.io/)

GSEGUtils provides some tools and functionality that are used across other development or research projects.
These are particularly focussed in the direction of research within the group.

The main goal if this repo is to help software development efforts and allow more focus on algorithm
development, data processing and research rather than code debugging and maintenance.

Currently this module includes:

| Package             | Description                                                                         |
|---------------------|-------------------------------------------------------------------------------------|
| **BaseArrays**      | Sub-classable array objects with automated validation on type, shape and attributes |
| **Lazy Disk Cache** | Automated data offloading for memory management                                     |
| **Util**            | Includes utility functions such as angle unit conversions                           |
| **Validators**      | Helper functions for performing validation and normalisation                        |

## Installation

This can be done directly from the repository directory:

```commandline
pip install git+ssh://git@github.com/gseg-ethz/GSEGUtils.git
```

or by cloning it

```commandline
git clone https://github.com/gseg-ethz/GSEGUtils.git
cd GSEGUtils
pip intstall .
 ```

## Usage
Accessing the different classes can then be easily done by importing from `GSEGUtils`:

```python
>>> from GSEGUtils.base_arrays import BaseArray, ArrayNx3, BaseVector
>>> import numpy as np
>>> data = np.random.rand(10,20,3)
>>> array = BaseArray(data)

>>> array.shape
(10, 20, 3)

>>> np.all(array == data)
np.True_

>>> a = ArrayNx3(np.random.rand(10, 3))
>>> b = a + 10
>>> np.all(b == a + 10)
np.True_

coords3D = Array_Nx3(np.random.rand(20, 3))
coords3d.arr = np.random.rand(100)
# RAISES ERROR -> invalid shape not of (N, 3), expected (N,)

coords3d.arr = np.random.rand(100, 3)
# Valid as the array is of shape Nx3
```

## Publication Policy

This package is internal to ETH Zurich's GSEG group and is not published to PyPI.
The `release-please` workflow produces build artefacts attached to GitHub Releases;
internal users install via `pip install <wheel-url>` from those releases. There is
no PyPI publish step; introducing one requires explicit ADR-level review.
