Initial release (v0.1.0) of point_utils module: support KDTree for of…

…fset vector computations

.dockerignore

@@ -0,0 +1,17 @@
+Dockerfile
+.coverage
+# Ignore Python cache files and directories
+**/__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Ignore Git files
+*.git
+*.gitignore
+
+# Ignore other temporary files
+*.DS_Store
+*.log
+*.tmp
+

.github/workflows/tests.yaml

@@ -0,0 +1,36 @@
+# Name of the workflow: Tests
+name: unit tests
+
+# Defines the events that trigger the workflow.
+# Here, the workflow runs on push and pull requests to the main branch.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+# jobs: Defines the tasks that the workflow will execute.
+# Here, there is a single job named test.
+jobs:
+  test:
+    # Set up an Ubuntu runner with the latest version of Ubuntu.
+    runs-on: ubuntu-latest
+
+    steps:
+    # Check out the repository code into the workflow runner.
+    # It allows subsequent steps to access the files in the repository.
+    - uses: actions/checkout@v3
+    # Configure Python environment.
+    - uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    # Install the package in editable mode (.) along with test dependencies
+    # defined in pyproject.toml
+    - run: pip install .[test]
+    # Execute the test suite using pytest.
+    - run: pytest --cov=modules --cov-report=xml
+    - uses: codecov/codecov-action@v3
+      with:
+        file: coverage.xml

.gitignore

@@ -0,0 +1,113 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*$py.class
+
+.vscode/
+.DS_Store
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# profraw files from LLVM? Unclear exactly what triggers this
+# There are reports this comes from LLVM profiling, but also Xcode 9.
+*profraw
+
+# In-tree generated files
+*/_version.py

AUTHORS.md

@@ -0,0 +1,5 @@
+# Author
+
+Copyright 2024
+
+- Renke Huang

Dockerfile

@@ -0,0 +1,27 @@
+# Use an official Python image as the base
+FROM python:3.9-slim
+
+# Set environment variables
+# Prevents the generation of .pyc files
+ENV PYTHONDONTWRITEBYTECODE=1
+# Ensures Python output is flushed immediately.
+ENV PYTHONUNBUFFERED=1
+
+# Set the working directory
+WORKDIR /app
+
+# Copy only files needed for installation to leverage Docker caching
+COPY pyproject.toml README.md ./
+COPY point_utils ./point_utils
+COPY scripts ./scripts
+COPY examples/cdd.txt     ./examples/cdd.txt
+COPY examples/config.yaml ./examples/config.yaml
+
+# Install pipenv and build dependencies
+RUN pip install --no-cache-dir setuptools wheel
+
+# Install the package in editable mode
+RUN pip install -e .
+
+# Default command (can be overridden in `docker run`)
+CMD ["python", "scripts/main.py", "-config", "examples/config.yaml"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 mqcomplab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,22 @@
+# Variables
+PIP = python -m pip
+
+# Default target
+install:
+	$(PIP) install -U pip setuptools wheel
+	$(PIP) install -e .
+
+# Install development dependencies
+dev:
+	$(PIP) install .[test]
+
+# Run tests
+test:
+	python -m pytest
+
+# Remove build artifacts, all __pycache__ directories.
+clean:
+	rm -rf dist/ *.egg-info/ build/ .eggs/
+	rm -rf .pytest_cache/ .coverage
+	find . -name "__pycache__" -type d -exec rm -rf {} +
+

README.md

@@ -0,0 +1,71 @@
+point_utils
+==============================
+<!-- [//]: # (Badges) -->
+
+
+**point_utils** is a Python package for computing offset points to a 3-D point cloud.
+
+## Installation
+You can install the package directly from the source using **pip**. Clone the repository and run the installation command
+```bash
+# Clone the repository
+git clone https://github.com/RenkeHuang/point_utils.git
+cd point_utils
+
+# Install the package
+python -m pip install .
+```
+### Editable Installation (For Development)
+If you plan to modify the package, you can install it in editable mode, or use
+**Makefile**:
+```bash
+python -m pip install -e .
+```
+### Testing
+```bash
+python -m pip install -r requirements-dev.txt
+# Alternatively, use pyproject.toml
+python -m pip install .[test]
+
+# Run pytest in the root of repository, with coverage reporting
+python -m pytest --cov=point_utils
+# Confirm all the test files and functions are found
+python -m pytest --collect-only
+
+# Cleanup using Makefile
+make clean
+```
+
+### Verify Installation
+```bash
+python -m scripts.main --help
+# Alternatively, use the provided script entry point
+RUN --help
+```
+
+### Example Usage:
+```bash
+RUN -config examples/config.yaml
+```
+### Build and Run Docker image
+```bash
+# Build the Docker image: run in the root directory where the Dockerfile is located
+docker build --no-cache -t point_utils:latest .
+
+# Run the Container and persist the output with Docker volume (map examples directory inside the container to the examples directory on local host)
+docker run --rm --name point_utils_container -v $(PWD)/examples:/app/examples point_utils:latest
+
+# If starting the Container with an interactive shell, manually execute the entry script in the shell
+# -i: keep STDIN open, -t: allocate a pseudo-TTY for the shell session.
+# /bin/bash: open a bash shell inside the container.
+docker run --rm -it --name point_utils_container point_utils:latest /bin/bash
+RUN -config examples/config.yaml
+
+# Override the default CMD:
+# The following command generates a plot for the data, and copy back to local host
+docker run --rm -v $(PWD)/examples:/app/examples point_utils:latest python scripts/visualize.py examples/cdd.txt -o examples/fig.png
+```
+
+
+## Background
+

examples/cdd.txt

@@ -0,0 +1,24 @@
+A 2.364336291362326 -0.44883814605376876 0.6454881665192085
+A 0.9659818332878829 -0.11585200546928814 0.396333030766464
+B 0.6995064705924114 1.2908952510271319 0.18538401937642307
+A 0.04246811915205344 1.4998554610066457 -1.1420644099608024
+A 0.01183063770153904 0.1415877179059355 -1.8120906254403912
+B 0.225822553703802 -0.8405517187692366 -0.6339943358848682
+A 0.7393768400286543 -2.2177682624583763 -1.0084161842167025
+B -1.4899168025857878 -1.0791516443976985 0.1355454892332844
+A -1.3796931966990311 -1.902953909506316 1.341685374377454
+A -2.445993481509025 -1.4398371813139113 -0.924699961414389
+B -1.8149784097102608 0.7513947979694862 0.6194486611697254
+A -2.7889984801225802 1.0158076198931865 1.2520156114750844
+A -0.7793565492338431 1.693219551744088 0.14668003395837725
+B 2.451610321498171 -1.5007761920214786 0.9124781829805815
+B 2.710517100059288 0.12851209786678194 1.5042709277372244
+B 3.0358578419514 -0.24173699597430698 -0.2022895057665115
+B 1.3930511745224012 1.9831317790494316 0.644570420300723
+B 0.1995755109605353 2.3903186948090327 -1.738393524191237
+B 0.8531631907495796 0.06674356200214872 -2.510216905404307
+B -0.9018291888967229 -0.07790802143970282 -2.364367829210351
+B 0.053796644179489726 -2.6796835309656135 -1.7208411108578392
+B 0.8071186991626855 -2.8683383955258837 -0.13583500519676447
+B 1.7227493457088723 -2.1491580567187616 -1.479254435503016
+B -1.006504099828904 2.7207843495398523 0.4110083546374142

examples/config.yaml

@@ -0,0 +1,4 @@
+input_file: "examples/cdd.txt"
+offset_magnitude: 2
+output_file: "examples/output.txt"
+visualize: false

point_utils/__init__.py

@@ -0,0 +1,3 @@
+from .utils import *
+from .settings import *
+from .offsetter import *