subsetdic 0.1.0__tar.gz

subsetdic-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,75 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    name: Build ${{ matrix.os }} distributions
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v4.1.0
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/subsetdic
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

subsetdic-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,52 @@
+name: Build wheels
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build ${{ matrix.os }} wheels
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v4.1.0
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz

subsetdic-0.1.0/.gitignore

@@ -0,0 +1,237 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# 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/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Native extension / CMake build artifacts
+_skbuild/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+compile_commands.json
+*.cmake
+*.vcxproj
+*.vcxproj.filters
+*.sln
+*.pyd
+*.pdb
+*.ilk
+*.exp
+
+# Generated DIC case outputs
+case/**/result/
+reference_code/

subsetdic-0.1.0/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.21)
+project(subsetdic VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_core
+    src/cpp/bindings.cpp
+    src/cpp/interpolation.cpp
+    src/cpp/solver.cpp
+    src/cpp/region.cpp
+    src/cpp/seeds.cpp
+    src/cpp/rgdic.cpp
+    src/cpp/strain.cpp
+    src/cpp/extrapolate.cpp
+)
+
+target_include_directories(_core PRIVATE src/cpp)
+target_compile_definitions(_core PRIVATE VERSION_INFO="0.1.0")
+
+install(TARGETS _core DESTINATION subsetdic)

subsetdic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LeeBDa
+
+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.

subsetdic-0.1.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.2
+Name: subsetdic
+Version: 0.1.0
+Summary: C++ implementation of Subset-DIC algorithms with Python bindings
+License: MIT License
+         
+         Copyright (c) 2026 LeeBDa
+         
+         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.
+         
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20
+Requires-Dist: opencv-python>=4.5
+Requires-Dist: opencv-contrib-python>=4.5
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# SubsetDIC
+
+SubsetDIC is a Python package for 2D subset-based digital image correlation
+(DIC). The performance-critical algorithms are implemented in C++ and exposed
+to Python through pybind11.
+
+This project is based on the algorithm flow of Ncorr and keeps the original
+Ncorr reference source under `reference_code/` for comparison.
+
+## Features
+
+- Subset-based 2D DIC for grayscale image pairs.
+- C++ core with Python API.
+- ROI-based region extraction.
+- SIFT or manual seed selection.
+- Region-growing DIC propagation.
+- Optional displacement-gradient / strain-field calculation.
+- Example `ring` and `star` cases under `case/`.
+
+## Project Layout
+
+```text
+SubsetDIC/
+|-- src/
+|   |-- subsetdic/        # Python API and configuration helpers
+|   `-- cpp/              # C++ DIC core and pybind11 bindings
+|-- config/
+|   `-- default.yaml      # Default DIC parameters
+|-- case/
+|   |-- ring/             # Example ring images and ROI
+|   `-- star/             # Example star displacement images and ROI
+|-- tests/
+|   |-- test_dic.py       # Synthetic translation integration test
+|   `-- run_cases.py      # Run bundled ring/star cases
+`-- reference_code/       # Ncorr MATLAB/C++ reference implementation
+```
+
+## Installation
+
+Requirements:
+
+- Python 3.9+
+- CMake 3.21+
+- A C++17 compiler
+- Visual Studio C++ Build Tools on Windows
+
+Install in editable mode:
+
+```powershell
+python -m pip install -e .
+```
+
+This compiles the C++ extension module `_core`. In editable mode, Python source
+files are loaded from this repository, while the compiled extension may be
+installed into your Python environment's `site-packages`, for example:
+
+```text
+C:\Users\<user>\miniconda3\Lib\site-packages\subsetdic\_core.cp312-win_amd64.pyd
+```
+
+After changing files in `src/cpp/`, run the install command again to rebuild
+the extension.
+
+## Quick Start
+
+```python
+import numpy as np
+from PIL import Image
+from subsetdic import SubsetDIC
+
+ref = np.array(Image.open("case/star/001.bmp")).astype(np.float64)
+cur = np.array(Image.open("case/star/002.bmp")).astype(np.float64)
+roi = (np.array(Image.open("case/star/003.bmp")) > 128).astype(np.uint8)
+
+dic = SubsetDIC({
+    "dic": {
+        "radius": 5,
+        "spacing": 1,
+        "cutoff_diffnorm": 1e-6,
+        "cutoff_iteration": 50,
+        "subsettrunc": False,
+    },
+    "seeds": {
+        "method": "manual",
+        "n_seeds": 1,
+        "manual_positions": [(512, 128)],
+    },
+    "strain": {
+        "enabled": True,
+        "radius": 15,
+    },
+    "border": {
+        "bcoef": 5,
+        "interp": 5,
+        "extrap": 5,
+    },
+})
+
+result = dic.run(ref, cur, roi)
+
+print(result.success)
+print(result.u.shape, result.v.shape)
+print(result.valid.sum())
+```
+
+## API
+
+The main entry point is:
+
+```python
+from subsetdic import SubsetDIC
+
+dic = SubsetDIC(config)
+result = dic.run(ref_img, def_img, roi_mask=None)
+```
+
+Inputs:
+
+- `ref_img`: reference image, 2D array.
+- `def_img`: deformed/current image, 2D array with the same shape.
+- `roi_mask`: optional 2D mask. Non-zero pixels are included in DIC.
+
+`DicResult` fields:
+
+- `success`: whether DIC produced a result.
+- `u`, `v`: displacement fields.
+- `corrcoef`: correlation residual field.
+- `valid`: valid point mask.
+- `dudx`, `dudy`, `dvdx`, `dvdy`: displacement gradients, available when
+  strain calculation is enabled.
+- `points_computed`: number of propagated valid points.
+- `regions`: ROI regions generated from the mask.
+
+## Configuration
+
+Default parameters live in `config/default.yaml`.
+
+```yaml
+dic:
+  radius: 20
+  spacing: 1
+  cutoff_diffnorm: 1.0e-6
+  cutoff_iteration: 50
+  subsettrunc: true
+  direct_seed_grid: false
+
+seeds:
+  method: sift
+  n_seeds: 1
+
+strain:
+  enabled: true
+  radius: 5
+
+postprocess:
+  enabled: true
+  max_iterations: 8
+  min_neighbors: 3
+  corrcoef_threshold: 2.0
+
+border:
+  bcoef: 20
+  interp: 20
+  extrap: 20
+```
+
+Important parameters:
+
+- `dic.radius`: subset radius in pixels.
+- `dic.spacing`: grid spacing between calculated DIC points.
+- `dic.cutoff_diffnorm`: IC-GN convergence threshold.
+- `dic.cutoff_iteration`: maximum IC-GN iterations.
+- `dic.subsettrunc`: whether to truncate subsets near ROI boundaries.
+- `dic.direct_seed_grid`: solve each grid point with seed-style local search
+  instead of region-growing propagation. This is slower but more robust for
+  periodic or highly nonuniform displacement fields such as the star case.
+- `seeds.method`: `sift` for automatic seeds or `manual` for fixed positions.
+- `seeds.manual_positions`: list of `(x, y)` seed coordinates when using
+  manual seeds.
+- `strain.enabled`: whether to compute displacement gradients.
+- `strain.radius`: radius used for gradient fitting.
+- `postprocess.enabled`: interpolate bad displacement points from neighboring
+  valid points before strain calculation.
+- `postprocess.max_iterations`: maximum neighbor-growing fill iterations.
+- `postprocess.min_neighbors`: minimum valid 8-neighbors required to fill a bad
+  point.
+- `postprocess.corrcoef_threshold`: points with larger correlation residual are
+  treated as bad during interpolation.
+
+You can also override selected DIC parameters when calling `run`:
+
+```python
+result = dic.run(ref, cur, roi, radius=15, spacing=3, compute_strain=False)
+```
+
+## Running Tests
+
+Run the synthetic translation test:
+
+```powershell
+python tests\test_dic.py
+```
+
+Expected output includes:
+
+```text
+PASSED
+All tests passed!
+```
+
+If `pytest` is installed, the same test can be run with:
+
+```powershell
+python -m pytest -q
+```
+
+## Running Example Cases
+
+Run bundled cases:
+
+```powershell
+python tests\run_cases.py
+```
+
+This runs:
+
+- `case/ring`
+- `case/star`
+
+Generated outputs are saved under each case's `result/` directory:
+
+- `u.npy`
+- `v.npy`
+- `corrcoef.npy`
+- `valid.npy`
+- `dudx.npy`, `dudy.npy`, `dvdx.npy`, `dvdy.npy` when strain is enabled
+- `overview.png`
+
+The `result/` directories are ignored by Git because they are generated files.
+
+## Development Notes
+
+- Python files under `src/subsetdic/` are used directly in editable installs.
+- C++ changes under `src/cpp/` require rebuilding with `python -m pip install -e .`.
+- The extension module is named `subsetdic._core`.
+- Arrays passed to the C++ core are stored in column-major/Fortran layout to
+  match the Ncorr-style indexing.
+- `reference_code/` contains the original Ncorr source used to check algorithm
+  behavior and edge cases.
+
+## License
+
+See `LICENSE`.