ezDIC is a lightweight dual-mode workstation for image sequences. The virtual-extensometer mode tracks two user-defined ROI markers and exports engineering strain, true strain, and quality-control results. The full-field mode correlates each deformation frame to one fixed reference frame, samples a rectangular ROI on a POI grid with IC-GN or IC-LM, and exports displacement and strain maps under dic/ for frames with a finite strain field.
Full-field coordinates and displacements are in px; strain components are dimensionless, and Exy/exy are tensor shear components. The fixed full-field core outputs are tabular data plus u/v/Exx/Eyy/Exy maps. An Exx overlay is optional. The result is a POI grid, not a per-pixel or 3D measurement.
Failed tracking frames and failed POIs remain NaN rather than being silently interpolated. A full-field frame with no finite strain points is skipped as a failed frame, and a run with no finite strain points fails instead of being reported as completed.
", @@ -31,11 +31,12 @@ ], "related_identifiers": [ { - "identifier": "https://github.com/D-sudoasd/ezDIC", + "identifier": "https://github.com/D-sudoasd/StrainTrace", "relation": "isSupplementTo", "resource_type": "software", "scheme": "url" } ], - "notes": "Developed by Dr. Delun Gong. Release date: 2026-08-30. DOI: 10.5281/zenodo.20222465. Recommended citation: Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465. Users are not permitted to claim authorship, remove or alter attribution, redistribute the software to unauthorized users, or use it outside the authorized research or teaching context." + "notes": "Metadata for a future archive of the MIT-licensed source candidate. Not an update to the historical DOI 10.5281/zenodo.20222465. The source retains legacy version 0.1.4; select a distinct final version after review.", + "license": "mit" } diff --git a/CITATION.cff b/CITATION.cff index ec32fb5..6d91cba 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,35 +1,18 @@ cff-version: 1.2.0 -title: ezDIC -message: "If ezDIC supports your research, please cite the Zenodo DOI: 10.5281/zenodo.20222465." +message: "Please cite StrainTrace with the exact source commit used until the current candidate has its own version archive." type: software +title: "StrainTrace: Virtual extensometry and in-plane digital image correlation" authors: - family-names: Gong given-names: Delun - name-particle: Dr. + email: dlgong17s@imr.ac.cn + affiliation: "Institute of Metal Research, Chinese Academy of Sciences, Shenyang 110016, China" + orcid: "https://orcid.org/0000-0001-7877-7707" version: 0.1.4 -date-released: 2026-08-30 -doi: 10.5281/zenodo.20222465 -url: "https://github.com/D-sudoasd/ezDIC" -repository-code: "https://github.com/D-sudoasd/ezDIC" -abstract: "ezDIC is a lightweight dual-mode workstation for image sequences: a virtual extensometer for engineering and true strain histories, and an in-plane full-field 2D DIC workflow that correlates each deformation frame to one fixed reference frame and computes displacement and strain on a POI grid with IC-GN or IC-LM. Full-field x/y/u/v values are in px, strain is dimensionless, Exy/exy are tensor shear components, and failed points remain NaN; the result is not per-pixel or 3D DIC." -keywords: - - Digital image correlation - - virtual extensometer - - strain extraction - - engineering strain - - true strain - - materials testing - - full-field 2D DIC - - POI grid -license: LicenseRef-Proprietary-Research-Use -preferred-citation: - type: software - title: "ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences" - authors: - - family-names: Gong - given-names: Delun - name-particle: Dr. - version: 0.1.4 - date-released: 2026-08-30 - doi: 10.5281/zenodo.20222465 - url: "https://doi.org/10.5281/zenodo.20222465" +license: MIT +repository-code: "https://github.com/D-sudoasd/StrainTrace" +url: "https://github.com/D-sudoasd/StrainTrace" +identifiers: + - type: doi + value: "10.5281/zenodo.20222465" + description: "Historical ezDIC archive; not the current MIT preparation candidate." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ace023d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# Contributing + +Report reproducible defects or propose changes through GitHub issues and pull requests. +Include the source commit, operating system, Python version, a minimal permitted input, +configuration and observed/expected result. Remove private images and paths first. + +Install with `python -m pip install -e ".[test]"`, run `python -m pytest -q`, and +run the locked synthetic benchmark described in `docs/joss/validation.md`. +Numerical changes must retain displacement/strain conventions, explicit invalid states, +fixed-reference semantics and manifest verification. Add a regression for the original +failure; do not relax a locked tolerance merely to make an algorithm pass. + +Delun Gong maintains the project and reviews changes. There is no guaranteed response +time. Contributions are made under the MIT license. Credit substantive contributions +in the change history and assess software-paper authorship using JOSS criteria. diff --git a/LICENSE.txt b/LICENSE.txt index af9a9a0..c9d625a 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,30 +1,21 @@ -ezDIC Usage Terms -================= - -Version: 0.1.4 -Release date: 2026-08-30 - -Developer: -Dr. Delun Gong - -DOI: -10.5281/zenodo.20222465 - -This software was developed by Dr. Delun Gong for lightweight extraction of linear strain from image sequences. - -Recommended citation: -Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465 - -This repository is shared for research visibility, evaluation, and authorized research or teaching use. It is not released under an open-source license. - -Users are not permitted to: -1. claim that they developed this software; -2. remove or alter the developer attribution; -3. redistribute, copy, forward, or share this software with unauthorized users; -4. use this software outside the authorized research or teaching context. - -If you use ezDIC in a thesis, paper, presentation, or report, please cite the DOI above. - -If you need to share, reuse, modify, or redistribute this software, please obtain permission from Dr. Delun Gong first. - -Unless explicit written permission is granted, all rights are reserved. +MIT License + +Copyright (c) 2026 Delun Gong + +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. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..9d56eac --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,11 @@ +include README.md README_使用说明.txt LICENSE.txt NOTICE_Attribution_and_Usage.txt CITATION.cff VERSION.txt +include requirements*.txt build_release.ps1 *.spec start_ezDIC.bat +recursive-include docs *.md *.json *.txt *.cff +recursive-include paper *.md *.bib *.png *.svg *.py +recursive-include tests *.py +recursive-include schemas *.json +recursive-include benchmarks *.json +include RELEASE_NOTES*.md + +recursive-include docs/joss *.md *.json +include scripts/check_joss_artifacts.py diff --git a/NOTICE_Attribution_and_Usage.txt b/NOTICE_Attribution_and_Usage.txt index 6055f8a..62209db 100644 --- a/NOTICE_Attribution_and_Usage.txt +++ b/NOTICE_Attribution_and_Usage.txt @@ -1,25 +1,15 @@ -ezDIC Attribution and Usage Notice - -Version: 0.1.4 -Release date: 2026-08-30 +StrainTrace attribution and licensing Developer: Dr. Delun Gong -DOI: -10.5281/zenodo.20222465 - -This software was developed by Dr. Delun Gong for lightweight extraction of linear strain from image sequences. - -Recommended citation: -Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465 - -Users are not permitted to: -1. claim that they developed this software; -2. remove or alter the developer attribution; -3. redistribute, copy, forward, or share this software with unauthorized users; -4. use this software outside the authorized research or teaching context. - -If you need to share or reuse this software, please obtain permission from Dr. Delun Gong first. +The author authorized MIT licensing for the current repository source on +27 September 2026. See LICENSE.txt. Modification, commercial use and +redistribution are permitted under that license; preserve the copyright and +permission notice. Citation in scholarly work is requested, not an additional +license restriction. -If you use ezDIC in a thesis, paper, presentation, or report, please cite the DOI above. +Historical ezDIC archives retain their original records and terms. The old +archive DOI 10.5281/zenodo.20222465 is not an archive of this MIT candidate. +See docs/history/pre-mit/ for the superseded repository metadata and license. +No remote archive was changed by this source-license transition. diff --git a/README.md b/README.md index 4135058..7ca98a2 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ smoke-verified Windows asset. The current `main` source tree contains a narrowly scoped research-grade upgrade. It does **not** bump `VERSION.txt`, `CITATION.cff`, the Zenodo record, -or the DOI: those remain the v0.1.4 metadata of this source snapshot. The +or the existing DOI. The 27 September MIT preparation updates repository citation and license metadata; the archived DOI remains historical. The implemented development capability is a reproducible fixed-reference, local-subset, in-plane 2D DIC workflow plus the existing 1D virtual extensometer; it is not a claim of universal DIC superiority or experimental @@ -353,3 +353,37 @@ Gong, D. (2026). ezDIC (v0.1.4). Zenodo. https://doi.org/10.5281/zenodo.20222465 ``` See `CITATION.cff`, `NOTICE_Attribution_and_Usage.txt`, `LICENSE.txt`, and `RELEASE_NOTES_v0.1.4.md` for attribution, redistribution terms, and the release boundary. + +## JOSS preparation + +See the [submission guide](docs/joss/README.md) for the manuscript, verified author metadata, research-use evidence and final checks. This repository is being prepared for submission; no JOSS acceptance is claimed. + +## Installable Python package + +Python 3.11–3.13; desktop use requires Tk. Windows is the maintained desktop platform. +From a source checkout: + +```bash +python -m pip install ".[test]" +straintrace --help +straintrace-gui +``` + +For a reproducible numerical check, run from a different directory: + +```bash +straintrace benchmark --output straintrace-synthetic-check +``` + +This generates its own synthetic images and reports defined numerical gates. It is +not experimental accuracy or quality-threshold calibration. See [API](docs/API.md), +[contributing](CONTRIBUTING.md), and [support](SUPPORT.md). + +## Current license and historical archives + +The author authorized **MIT** licensing of the current source on 27 September 2026. +See [LICENSE.txt](LICENSE.txt). Historical ezDIC archives retain their original records; +[the historical metadata](docs/history/pre-mit/LICENSE.txt) does not govern this candidate. +The existing DOI is not an archive of the new MIT preparation. Legacy module names, +source version 0.1.4 and executable identity remain for compatibility; use the Git commit +to identify this candidate and choose a distinct final release version after review. diff --git "a/README_\344\275\277\347\224\250\350\257\264\346\230\216.txt" "b/README_\344\275\277\347\224\250\350\257\264\346\230\216.txt" index f1bdf88..5f38d47 100644 --- "a/README_\344\275\277\347\224\250\350\257\264\346\230\216.txt" +++ "b/README_\344\275\277\347\224\250\350\257\264\346\230\216.txt" @@ -1,3 +1,5 @@ +当前源码许可更新（2026-09-27）：StrainTrace 已获作者授权采用 MIT 许可。允许修改、商业使用和再分发，须保留版权与许可声明。旧 ezDIC 归档不代表当前候选版本；历史条款保留于 docs/history/pre-mit。 + ezDIC v0.1.4 使用说明 ====================== 发布日期：2026-08-30 @@ -6,7 +8,7 @@ ezDIC v0.1.4 使用说明 v0.2.0-dev 开发目标（尚未发布） ------------------------------ 当前 `main` 源码树已经实现一个有明确边界的研究级升级，但没有修改 `VERSION.txt`、 -`CITATION.cff`、Zenodo 元数据、许可证、作者署名或 DOI；这些仍是本源代码快照的 +历史归档 DOI；2026-09-27 的 JOSS 准备已更新源码许可及引用信息，源码版本仍为 v0.1.4 元数据。目标是固定参考、局部子集、面内 2D DIC 加现有 1D 虚拟引伸计， 不是“超过所有 DIC 软件”或“已证明适用于实验数据”的声明。 @@ -297,15 +299,9 @@ PoissonRatio = - ε_transverse / ε_axial (engineering) -------- Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465 -归属与使用限制 +当前源码许可 -------------- -用户不得： -1. 声称该软件由其开发； -2. 删除或修改开发者署名； -3. 向未经授权的用户重新分发、复制、转发或分享该软件； -4. 在获授权的科研或教学范围之外使用该软件。 - -如需分享、复用、修改或重新分发，请先联系 Dr. Delun Gong 获得许可。论文、学位论文、报告或演示文稿使用 ezDIC 时，请引用上述 DOI。具体条款见 LICENSE.txt 与 NOTICE_Attribution_and_Usage.txt。 +当前源码采用 MIT 许可。允许使用、复制、修改和再分发，须保留版权和许可声明。具体条款见 LICENSE.txt。上列 DOI 属于历史 ezDIC 归档，使用当前候选版本时请同时记录 Git 提交，勿将历史归档当作本次源码。 安全提示 -------- diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..e514d67 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,7 @@ +# Support and maintenance + +Use [GitHub issues](https://github.com/D-sudoasd/StrainTrace/issues) for installation, +usage questions and reproducible defects. Delun Gong is the maintainer; response times +are not guaranteed. For private correspondence use dlgong17s@imr.ac.cn. Do not attach +confidential experimental data to a public issue. Supply a minimal synthetic example +when possible and distinguish a program failure from insufficient image texture. diff --git a/build_release.ps1 b/build_release.ps1 index dfa6a1c..f809edd 100644 --- a/build_release.ps1 +++ b/build_release.ps1 @@ -402,15 +402,21 @@ function Test-ReleaseContracts { throw "CITATION.cff does not define a readable version." } if ($Matches[1] -ne $Version) { throw "CITATION.cff version $($Matches[1]) does not match $Version." } - if ($citationText -notmatch '(?m)^\s*date-released:\s*2026-08-30\s*$') { - throw "CITATION.cff date-released must be 2026-08-30 for this source snapshot." + # An unreleased preparation candidate must not invent a release date. + $citationDate = $null + if ($citationText -match '(?m)^date-released:\s*([0-9]{4}-[0-9]{2}-[0-9]{2})\s*$') { + $citationDate = $Matches[1] } $zenodoText = Read-RequiredText (Join-Path $Root ".zenodo.json") try { $zenodo = $zenodoText | ConvertFrom-Json } catch { throw ".zenodo.json is not valid JSON: $($_.Exception.Message)" } if ([string]$zenodo.version -ne $Version) { throw ".zenodo.json version $($zenodo.version) does not match $Version." } - if ([string]$zenodo.publication_date -ne "2026-08-30") { throw ".zenodo.json publication_date must be 2026-08-30." } + $zenodoDate = $zenodo.PSObject.Properties["publication_date"] + $publicationDate = if ($null -eq $zenodoDate) { $null } else { [string]$zenodoDate.Value } + if ([string]$publicationDate -ne [string]$citationDate) { + throw "CITATION.cff and .zenodo.json release dates must agree, or both be absent for an unreleased candidate." + } $specText = Read-RequiredText (Join-Path $Root "ezDIC.spec") if ($specText -notmatch 'name\s*=\s*[''\"]ezDIC[''\"]') { throw "ezDIC.spec does not define the ezDIC executable." } diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..c04bc2a --- /dev/null +++ b/docs/API.md @@ -0,0 +1,23 @@ +# Headless interfaces + +`straintrace --help` and `python -m ezdic_cli --help` expose the same interface. + +- `validate-config --config run.json`: validate and print normalized version-1 JSON. +- `run --config run.json --progress-json`: execute a permitted image sequence. +- `verify-manifest --manifest PATH`: verify the recorded output bundle (see `--help` for syntax). +- `benchmark --output PATH`: run the locked, generated verification cases. + +The schema is in `schemas/run_config_v1.json` in source and `straintrace_data` in the +wheel. The README contains complete extensometer and full-field configuration examples. +Unknown fields and non-finite configuration numbers are rejected. + +Python interfaces: `ezdic_cli.normalize_config(mapping, base_dir=path)` returns the +canonical configuration; `ezdic_cli.main(argv)` returns a process exit status; +`ezdic_benchmark.run_benchmark(output_dir=path)` returns a machine-readable report. +`ezdic_core` contains the GUI-independent numerical implementation. Private helpers +are not a stability promise; prefer the versioned JSON interface for integration. + +Coordinates and displacement are in pixels. Strain is dimensionless; tensor shear +must not be interpreted as engineering shear. Retain both displacement-valid and +strain-valid indicators. A verified checksum establishes integrity, not measurement +accuracy. A successful synthetic benchmark does not calibrate experimental uncertainty. diff --git a/docs/history/pre-mit/.zenodo.json b/docs/history/pre-mit/.zenodo.json new file mode 100644 index 0000000..d8a884f --- /dev/null +++ b/docs/history/pre-mit/.zenodo.json @@ -0,0 +1,41 @@ +{ + "title": "ezDIC: Lightweight Virtual Extensometer for Linear Strain Extraction from Image Sequences", + "upload_type": "software", + "version": "0.1.4", + "publication_date": "2026-08-30", + "language": "eng", + "access_right": "restricted", + "access_conditions": "Access is granted for authorized research or teaching use. Contact Dr. Delun Gong for permission before redistribution, reuse outside the authorized context, or derivative use.", + "creators": [ + { + "name": "Gong, Delun" + } + ], + "description": "ezDIC is a lightweight dual-mode workstation for image sequences. The virtual-extensometer mode tracks two user-defined ROI markers and exports engineering strain, true strain, and quality-control results. The full-field mode correlates each deformation frame to one fixed reference frame, samples a rectangular ROI on a POI grid with IC-GN or IC-LM, and exports displacement and strain maps under dic/ for frames with a finite strain field.
Full-field coordinates and displacements are in px; strain components are dimensionless, and Exy/exy are tensor shear components. The fixed full-field core outputs are tabular data plus u/v/Exx/Eyy/Exy maps. An Exx overlay is optional. The result is a POI grid, not a per-pixel or 3D measurement.
Failed tracking frames and failed POIs remain NaN rather than being silently interpolated. A full-field frame with no finite strain points is skipped as a failed frame, and a run with no finite strain points fails instead of being reported as completed.
", + "keywords": [ + "digital image correlation", + "full-field 2D DIC", + "POI grid", + "IC-GN", + "IC-LM", + "virtual extensometer", + "strain extraction", + "engineering strain", + "true strain", + "materials testing", + "tensile testing", + "image sequence analysis", + "Origin-compatible TXT", + "Python", + "OpenCV" + ], + "related_identifiers": [ + { + "identifier": "https://github.com/D-sudoasd/ezDIC", + "relation": "isSupplementTo", + "resource_type": "software", + "scheme": "url" + } + ], + "notes": "Developed by Dr. Delun Gong. Release date: 2026-08-30. DOI: 10.5281/zenodo.20222465. Recommended citation: Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465. Users are not permitted to claim authorship, remove or alter attribution, redistribute the software to unauthorized users, or use it outside the authorized research or teaching context." +} diff --git a/docs/history/pre-mit/CITATION.cff b/docs/history/pre-mit/CITATION.cff new file mode 100644 index 0000000..ec32fb5 --- /dev/null +++ b/docs/history/pre-mit/CITATION.cff @@ -0,0 +1,35 @@ +cff-version: 1.2.0 +title: ezDIC +message: "If ezDIC supports your research, please cite the Zenodo DOI: 10.5281/zenodo.20222465." +type: software +authors: + - family-names: Gong + given-names: Delun + name-particle: Dr. +version: 0.1.4 +date-released: 2026-08-30 +doi: 10.5281/zenodo.20222465 +url: "https://github.com/D-sudoasd/ezDIC" +repository-code: "https://github.com/D-sudoasd/ezDIC" +abstract: "ezDIC is a lightweight dual-mode workstation for image sequences: a virtual extensometer for engineering and true strain histories, and an in-plane full-field 2D DIC workflow that correlates each deformation frame to one fixed reference frame and computes displacement and strain on a POI grid with IC-GN or IC-LM. Full-field x/y/u/v values are in px, strain is dimensionless, Exy/exy are tensor shear components, and failed points remain NaN; the result is not per-pixel or 3D DIC." +keywords: + - Digital image correlation + - virtual extensometer + - strain extraction + - engineering strain + - true strain + - materials testing + - full-field 2D DIC + - POI grid +license: LicenseRef-Proprietary-Research-Use +preferred-citation: + type: software + title: "ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences" + authors: + - family-names: Gong + given-names: Delun + name-particle: Dr. + version: 0.1.4 + date-released: 2026-08-30 + doi: 10.5281/zenodo.20222465 + url: "https://doi.org/10.5281/zenodo.20222465" diff --git a/docs/history/pre-mit/LICENSE.txt b/docs/history/pre-mit/LICENSE.txt new file mode 100644 index 0000000..af9a9a0 --- /dev/null +++ b/docs/history/pre-mit/LICENSE.txt @@ -0,0 +1,30 @@ +ezDIC Usage Terms +================= + +Version: 0.1.4 +Release date: 2026-08-30 + +Developer: +Dr. Delun Gong + +DOI: +10.5281/zenodo.20222465 + +This software was developed by Dr. Delun Gong for lightweight extraction of linear strain from image sequences. + +Recommended citation: +Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465 + +This repository is shared for research visibility, evaluation, and authorized research or teaching use. It is not released under an open-source license. + +Users are not permitted to: +1. claim that they developed this software; +2. remove or alter the developer attribution; +3. redistribute, copy, forward, or share this software with unauthorized users; +4. use this software outside the authorized research or teaching context. + +If you use ezDIC in a thesis, paper, presentation, or report, please cite the DOI above. + +If you need to share, reuse, modify, or redistribute this software, please obtain permission from Dr. Delun Gong first. + +Unless explicit written permission is granted, all rights are reserved. diff --git a/docs/history/pre-mit/NOTICE_Attribution_and_Usage.txt b/docs/history/pre-mit/NOTICE_Attribution_and_Usage.txt new file mode 100644 index 0000000..6055f8a --- /dev/null +++ b/docs/history/pre-mit/NOTICE_Attribution_and_Usage.txt @@ -0,0 +1,25 @@ +ezDIC Attribution and Usage Notice + +Version: 0.1.4 +Release date: 2026-08-30 + +Developer: +Dr. Delun Gong + +DOI: +10.5281/zenodo.20222465 + +This software was developed by Dr. Delun Gong for lightweight extraction of linear strain from image sequences. + +Recommended citation: +Gong, D. (2026). ezDIC: A lightweight virtual extensometer for extracting linear strain from image sequences (Version 0.1.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20222465 + +Users are not permitted to: +1. claim that they developed this software; +2. remove or alter the developer attribution; +3. redistribute, copy, forward, or share this software with unauthorized users; +4. use this software outside the authorized research or teaching context. + +If you need to share or reuse this software, please obtain permission from Dr. Delun Gong first. + +If you use ezDIC in a thesis, paper, presentation, or report, please cite the DOI above. diff --git a/docs/joss/README.md b/docs/joss/README.md new file mode 100644 index 0000000..b03cc66 --- /dev/null +++ b/docs/joss/README.md @@ -0,0 +1,25 @@ +# StrainTrace: JOSS submission preparation + +Preparation record: 27 September 2026. This is a preparation candidate, not a submitted or accepted paper. + +## Start here + +- [Manuscript](../../paper/paper.md), [bibliography](../../paper/paper.bib). +- [Author, policy, and evidence record](submission-record.json). +- [Research-use record](research-use.md). +- [Validation instructions](validation.md). + +The manuscript date is a **draft preparation date**. Set it to the actual submission day before sending. The software source version is 0.1.4; identify every tested and submitted candidate by its Git commit as well as version. Do not attach a historical archive DOI to this new source as an exact-version archive. + +## Remaining author and time-dependent checks + +1. Confirm the actual public-availability date from public releases, issue/PR records, or visibility records. Repository creation (2026-05-16) is not proof that it was public at creation. The conditional planning date 2026-11-17 assumes public availability from creation; later public availability moves the date later. Continue real maintenance driven by use and feedback. Automated runs and empty commits do not establish iteration. +2. Complete the historical revision, specific operations, and processing-record location in the research-use record. Keep private experimental inputs private; prepare an editor-visible explanation or permitted supporting records. Synthetic fixtures check software, not experimental adoption. +3. The sole author must review the final code, paper, figures and AI-assisted changes and confirm the updated disclosure. Earlier review of another package or version cannot cover these changes. +4. Refresh policy, repository status, installation, tests, examples, references, and the official PDF on the exact submission commit. Download CI artifacts before their retention period expires. Set the actual submission date and check the PDF again. +5. Submit the repository URL and `paper/paper.md` location through JOSS. Disclose the related Acta Materialia study and any additional related publications or submissions. The same research-use study can support several tools only with each tool's actual role distinguished. +6. After successful review, create the agreed version tag and immutable software archive, verify the version DOI, and report them in the review issue. Do not invent a JOSS paper DOI or mark this candidate accepted. + +JOSS requires an OSI-approved license, more than six months of public development with substantive iteration, actual research use, and good open-source practices. External users are welcome but are not a universal numeric gate. No checklist can substitute for editorial scope assessment. Official sources, checked 2026-09-27: [submission](https://joss.readthedocs.io/en/latest/submitting.html), [paper](https://joss.readthedocs.io/en/latest/paper.html), [review](https://joss.readthedocs.io/en/latest/review_criteria.html). + +AI assistance in development and paper preparation must be disclosed. Under the policy checked above, AI use in author conversations with editors/reviewers is limited to translation; the author should write substantive responses personally. diff --git a/docs/joss/research-use.md b/docs/joss/research-use.md new file mode 100644 index 0000000..fa937f3 --- /dev/null +++ b/docs/joss/research-use.md @@ -0,0 +1,20 @@ +# Research use of StrainTrace + +On 27 September 2026, Delun Gong confirmed that all four programs (RingSentry, DiffractScout, AnisoScope and StrainTrace) were used in his recent Acta Materialia research and directed this preparation to the completed AbsSAXS submission's article record. + +**Verified bibliographic record:** Gong et al., “Simultaneous improvement of strength and corrosion resistance in β-type Ti-24Nb-4Zr-8Sn alloy through a spinodally modulated dual-phase microstructure”, *Acta Materialia* **316** (2026), 122455. [DOI](https://doi.org/10.1016/j.actamat.2026.122455). Title, authors, volume and article number were checked through the Crossref DOI API on 27 September 2026. + +**Evidence level:** author-confirmed software use. Bibliographic verification does not independently establish which software ran. No claim is made that the article cites this program, that every current feature was used, or that the current candidate reproduces the historical analysis. + +Before submission, complete this concise mapping from the author's actual processing records: + +| Record | Current status | +|---|---| +| Historical software version/commit or dated source copy | Author record needed | +| Specific operations performed with StrainTrace | Author record needed | +| Input identifiers and output files used in the research | Author record needed; do not publish private data without permission | +| Associated analysis, figure, or research decision | Author record needed | +| Location of records available to the editor | Author record needed | +| Independent users | None confirmed in this preparation | + +These missing details do not negate the author's confirmation. They limit how specifically the manuscript can describe the application. Do not fill the table from the software's capability list or from AbsSAXS's distinct calibration role. diff --git a/docs/joss/submission-record.json b/docs/joss/submission-record.json new file mode 100644 index 0000000..c5bbdb6 --- /dev/null +++ b/docs/joss/submission-record.json @@ -0,0 +1,61 @@ +{ + "schema_version": 1, + "project": "StrainTrace", + "repository": "https://github.com/D-sudoasd/StrainTrace", + "version": "0.1.4", + "status": "preparation_candidate_not_submitted", + "policy_checked_on": "2026-09-27", + "policy_sources": [ + "https://joss.readthedocs.io/en/latest/submitting.html", + "https://joss.readthedocs.io/en/latest/paper.html", + "https://joss.readthedocs.io/en/latest/review_criteria.html" + ], + "author": { + "name": "Delun Gong", + "orcid": "0000-0001-7877-7707", + "email": "dlgong17s@imr.ac.cn", + "affiliation": "Institute of Metal Research, Chinese Academy of Sciences, Shenyang 110016, China", + "sole_author_confirmed_on": "2026-09-27", + "source": "Author explicitly confirmed sole authorship and directed reuse of the confirmed AbsSAXS identity and declarations in this preparation conversation on 2026-09-27." + }, + "declarations": { + "funding": "No external funding", + "sponsor_role": "Not applicable", + "competing_interests": "The author declares no competing interests", + "source": "Author-directed reuse of AbsSAXS confirmed declarations, 2026-09-27", + "human_review_of_this_revision_confirmed": false + }, + "history": { + "repository_created_on": "2026-05-16", + "public_since_verified": null, + "conditional_planning_date": "2026-11-17", + "note": "Creation date is a lower bound, not proof of public visibility. Verify public availability and substantive iteration spanning more than six calendar months; inspect releases/issues/PRs and visibility history before submission." + }, + "research_use": { + "status": "author_confirmed_records_not_audited", + "confirmed_on": "2026-09-27", + "doi": "10.1016/j.actamat.2026.122455", + "bibliographic_metadata_verified_with": "Crossref DOI API, 2026-09-27", + "statement": "The author confirmed that all four programs were used in the recent Acta Materialia study and identified it through the completed AbsSAXS submission materials.", + "historical_version": null, + "specific_operations_and_outputs": null, + "processing_record_location": null, + "cited_by_article": null, + "note": "Author confirmation establishes reported use, not independent reproduction or a verified software citation. Do not infer that the current version or every current feature was used." + }, + "ai_assistance": { + "current_round": "OpenAI Codex, GPT-6, 2026-09-27: repository audit, packaging, tests, documentation, manuscript and bibliography preparation, validation and Git integration.", + "historical_disclosure": "Retain project-specific disclosures; AbsSAXS AI history is not copied to these projects." + }, + "submission_date": null, + "related_publications": [ + { + "doi": "10.1016/j.actamat.2026.122455", + "relation": "Research application reported by author; disclose to editor." + } + ], + "archive": { + "current_candidate_version_doi": null, + "note": "Existing historical archives are not an archive of this candidate. Final accepted-version archive follows review." + } +} diff --git a/docs/joss/validation.md b/docs/joss/validation.md new file mode 100644 index 0000000..38005a1 --- /dev/null +++ b/docs/joss/validation.md @@ -0,0 +1,36 @@ +# Reproduce the candidate checks + +Run with the Python versions supported by the project. Create an isolated environment +first. Use a new output directory for each run; never overwrite research outputs. + +```bash +python -m pip install ".[test]" +python -m pytest -q +python -m ezdic_cli benchmark --output outputs/joss-benchmark +python -m pip install build PyYAML cffconvert +python -m build +cffconvert --validate -i CITATION.cff +python scripts/check_joss_artifacts.py +``` + +Install the generated wheel in a second empty environment. Leave the source directory, +then run the documented numerical example with that interpreter. Check `pip check`. +Record the Git commit, platform, Python/dependency versions, commands, exit status, +output paths and CI URLs. GUI construction tests are not a complete interactive-user +acceptance test. The source and installed distributions must agree. + +`check_joss_artifacts.py` checks paper sections, approximate prose word count, author +identity, bibliography keys, figure paths and citation metadata. It reports unresolved +submission checks without failing technical CI. Use `--submission` to return nonzero +while those records are incomplete. It does not validate the truth of author statements, +actual public history, current policy, experimental correctness or editorial eligibility. + +The draft-PDF workflow compiles the manuscript with Open Journals tooling. Download +its artifact for the selected commit and inspect every page, including references, +formulas, figure captions and author details. Rebuild after manuscript changes. The +paper date is a preparation date until the author selects the actual submission date. + +Final submission still requires a human check of substantive public iteration over +more than six months, the actual research-use mapping, author review of all assisted +work, current policy and related-publication disclosure. Record the selected SHA and +all evidence in the local submission package; do not replace failures with old CI. diff --git a/ezdic_cli.py b/ezdic_cli.py index 9215629..729e965 100644 --- a/ezdic_cli.py +++ b/ezdic_cli.py @@ -21,6 +21,10 @@ SCHEMA_VERSION = 1 SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "run_config_v1.json" +if not SCHEMA_PATH.is_file(): + from importlib.resources import files + + SCHEMA_PATH = Path(str(files("straintrace_data").joinpath("run_config_v1.json"))) EXIT_SUCCESS = 0 EXIT_CONFIG_ERROR = 2 EXIT_RUNTIME_ERROR = 3 diff --git a/paper/README.md b/paper/README.md new file mode 100644 index 0000000..d266553 --- /dev/null +++ b/paper/README.md @@ -0,0 +1,11 @@ +# StrainTrace JOSS manuscript + +`paper.md` and `paper.bib` are the maintained source. The GitHub Actions workflow +**Draft JOSS PDF** uses Open Journals tooling and publishes `straintrace-joss-paper`. +Select the artifact for the exact candidate commit; artifacts expire, so keep a local +copy with the submission package. The draft has no assigned JOSS DOI or acceptance. + +The source date is a preparation date. Before submission, complete the author review +and research-use mapping in [the submission guide](../docs/joss/README.md), use the +actual submission date, rebuild and inspect the PDF. The synthetic verification +suite is documented in [validation](../docs/joss/validation.md). diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 0000000..a66d27b --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,28 @@ + +@article{gong2026acta, + author = {Gong, Delun and Wei, Boxin and Li, Wenjie and Liu, Yujing and Zhao, Zibo and Kumara, L. S. R. and Ren, Yang and Yang, Rui and Ramamurty, Upadrasta and Hao, Yulin}, + title = {Simultaneous improvement of strength and corrosion resistance in {$\beta$}-type {Ti-24Nb-4Zr-8Sn} alloy through a spinodally modulated dual-phase microstructure}, + journal = {Acta Materialia}, + volume = {316}, + pages = {122455}, + year = {2026}, + doi = {10.1016/j.actamat.2026.122455} +} + +@article{blaber2015ncorr, + author = {Blaber, J. and Adair, B. and Antoniou, A.}, + title = {{Ncorr}: Open-Source {2D} Digital Image Correlation Matlab Software}, + journal = {Experimental Mechanics}, + volume = {55}, + number = {6}, + pages = {1105--1122}, + year = {2015}, + doi = {10.1007/s11340-015-0009-1} +} +@misc{dice, + author = {{DICe developers}}, + title = {Digital Image Correlation Engine ({DICe})}, + url = {https://github.com/dicengine/dice}, + year = {2026}, + note = {Project documentation accessed 27 September 2026} +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 0000000..3050cdb --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,144 @@ +--- +title: 'StrainTrace: Virtual extensometry and fixed-reference digital image correlation' +tags: + - Python + - digital image correlation + - experimental mechanics + - strain measurement +authors: + - name: Delun Gong + orcid: 0000-0001-7877-7707 + email: dlgong17s@imr.ac.cn + corresponding: true + affiliation: 1 +affiliations: + - name: Institute of Metal Research, Chinese Academy of Sciences, Shenyang 110016, China + index: 1 +date: 27 September 2026 +bibliography: paper.bib +--- + +# Summary + +Image sequences recorded during mechanical tests can provide both gauge-length +changes and spatially resolved deformation. These measurements require different +analysis choices: a virtual extensometer follows selected image regions, whereas +digital image correlation estimates a displacement field and differentiates that +field to obtain strain. StrainTrace is a Python desktop application and headless +analysis tool that exposes both workflows while retaining their distinct output +semantics. It provides a two-region virtual extensometer and a fixed-reference, +local-subset, in-plane two-dimensional digital image correlation workflow. Its +outputs include numerical tables, diagnostic fields, configuration records and +verifiable file manifests. StrainTrace retains the historical ezDIC module and +executable names for compatibility. The current repository source is MIT licensed; +older ezDIC archives remain separate historical records. + +# Statement of need + +Materials researchers often need an image-derived strain history to accompany +a mechanical test, and may subsequently need to determine whether deformation +varies across the observed surface. Moving between gauge measurements, correlation +software and plotting tools can obscure which reference image, region, validity +criterion and strain convention generated a reported value. A failed correlation +must also remain distinguishable from a measured small displacement. StrainTrace +addresses this recording and inspection problem through a common local workbench +and a versioned configuration interface. + +The virtual extensometer reports engineering and true strain from selected region +pairs, with diagnostic information for the tracking step. The full-field workflow +correlates each deformation image to the selected fixed reference, evaluates a +grid of points within a rectangular region, and exports displacement and strain +maps. Its measurements are sampled on that grid, not at every image pixel. The +software is intended for in-plane image sequences with suitable texture; it does +not implement stereo reconstruction, volumetric correlation, or correction for +out-of-plane motion. These scope limits matter when an image-derived strain is +used to interpret a mechanical experiment. + +# State of the field + +Digital image correlation is an established measurement approach. Ncorr provides +an open-source two-dimensional implementation in MATLAB [@blaber2015ncorr]. DICe +provides full-field displacement and strain analysis, object tracking, and support +for stereo applications and parallel execution [@dice]. These projects already +address extensive correlation needs. StrainTrace does not claim a new correlation +theory or general accuracy or speed superiority over them. + +The contribution is a focused Python workflow that combines a virtual +extensometer, local full-field analysis and explicit recording of the decisions +needed to interpret their outputs. The desktop and headless interfaces share the +numerical core. Configuration normalization, separate displacement and strain +validity, failed-frame handling and output verification are part of the application +contract. This choice supports scripted laboratory workflows without requiring +MATLAB, while preserving a desktop interface for selecting image regions. It +trades the scope of a general stereo or high-performance correlation framework +for a narrower implementation that can be exercised through generated regression +cases. Researchers requiring the broader capabilities should use the appropriate +established package rather than interpret this scope as a substitute. + +# Software design + +StrainTrace separates its numerical and export functions from the Tk desktop +interface. The command-line interface validates a versioned JSON configuration, +normalizes defaults and rejects unknown fields or non-finite values. The same +core can therefore be invoked without importing the GUI. Existing ezDIC imports +remain available, while the installable package exposes StrainTrace command-line +and desktop entry points. Origin export is optional; numerical tables and normal +analysis do not require Origin. + +For full-field correlation, every selected deformation frame is compared with one +fixed reference. Reference-based normalization and bounded multiscale +initialization precede the implemented inverse-compositional Gauss--Newton or +Levenberg--Marquardt solution. Solver diagnostics accompany accepted and rejected +points. A displacement-valid point need not have a valid local strain estimate, +so the outputs retain separate validity fields. Coordinates and displacements are +in pixels; strain is dimensionless. Green--Lagrange and infinitesimal strain +components are identified separately, and off-diagonal components use tensor +shear rather than engineering shear. Unsuccessful measurements remain missing +values, rather than being interpolated into apparently complete fields. + +Full-field outputs are prepared in a staging directory. Completed results are +published with recorded input identities, configuration and source fingerprints; +earlier successful outputs are retained under a previous-run directory. A frame +with no valid strain field is recorded as failed and skipped, while other usable +frames can still produce results. A run without any valid strain field fails. +These distinctions prevent a directory containing some output files from being +interpreted automatically as a successful scientific analysis. + +The automated tests exercise the configuration interface, numerical and export +behavior, failure conditions and preservation of previous results. A locked +synthetic benchmark supplies small and large translations, a prescribed affine +strain, and a near-one-dimensional periodic texture case. Its generated inputs, +fixed conditions, source hashes and numerical diagnostics make the verification +repeatable from an installed distribution. Translation and strain cases test +specified numerical behavior; the ambiguous texture case tests failure reporting. +The benchmark also distinguishes quality ranking from calibration of a quality +threshold. Passing it does not establish uncertainty for an experimental camera, +specimen or texture, and the paper makes no such claim. + +# Research impact statement + +On 27 September 2026, the author confirmed using StrainTrace in the research +underlying the Ti-24Nb-4Zr-8Sn study reported by Gong et al. [@gong2026acta]. This +is an author-confirmed research application, not a claim that the article cites +StrainTrace or that the current full-field implementation was used in that study. +The historical source revision and the specific operations and outputs must be +mapped to the author's processing records before submission. The repository's +research-use record separates that outstanding mapping from the present synthetic +verification suite. No independent-user adoption or experimental accuracy is +inferred from the repository's availability or benchmark results. + +# AI usage disclosure + +OpenAI Codex (GPT-6) assisted the September 2026 preparation with repository +inspection, Python packaging, tests, documentation, bibliography and manuscript +drafting, and automated verification. The complete history of earlier AI +assistance has not been confirmed for this software. The sole author must review, +edit and validate the assisted outputs and confirm the complete disclosure and +human responsibility for scientific and design decisions before submission. + +# Acknowledgements + +No external funding was received for this software. There was no sponsor +involvement. The author declares no competing interests. + +# References diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..617e4fb --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,42 @@ +[build-system] +requires = ["setuptools>=77", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "straintrace" +version = "0.1.4" +description = "Virtual extensometry and fixed-reference in-plane digital image correlation" +readme = "README.md" +requires-python = ">=3.11,<3.14" +license = "MIT" +license-files = ["LICENSE.txt"] +authors = [{name = "Delun Gong", email = "dlgong17s@imr.ac.cn"}] +dependencies = ["opencv-python>=4.8", "numpy>=1.26", "pandas>=2", "matplotlib>=3.8", "pillow>=10"] + +[project.optional-dependencies] +test = ["pytest>=8", "build>=1.2", "cffconvert>=2", "PyYAML>=6"] +origin = ["originpro; sys_platform == 'win32'"] + +[project.scripts] +straintrace = "ezdic_cli:main" +ezdic-cli = "ezdic_cli:main" + +[project.gui-scripts] +straintrace-gui = "dic_virtual_extensometer_gui_v7_multi_roi_range:main" + +[project.urls] +Repository = "https://github.com/D-sudoasd/StrainTrace" +Issues = "https://github.com/D-sudoasd/StrainTrace/issues" +Documentation = "https://github.com/D-sudoasd/StrainTrace#readme" + +[tool.setuptools] +py-modules = ["ezdic_core", "ezdic_cli", "ezdic_benchmark", "ezdic_cli_entrypoint", "ezdic_frozen_entrypoint", "dic_virtual_extensometer_gui_v7_multi_roi_range"] +packages = ["benchmarks", "straintrace_data"] +package-dir = {straintrace_data = "schemas"} + +[tool.setuptools.package-data] +benchmarks = ["cases_v1.json"] +straintrace_data = ["run_config_v1.json"] + +[tool.pytest.ini_options] +testpaths = ["tests"] diff --git a/schemas/__init__.py b/schemas/__init__.py new file mode 100644 index 0000000..76dce3c --- /dev/null +++ b/schemas/__init__.py @@ -0,0 +1 @@ +"""JSON schemas distributed as straintrace_data in installed packages.""" diff --git a/scripts/check_joss_artifacts.py b/scripts/check_joss_artifacts.py new file mode 100644 index 0000000..4f849c0 --- /dev/null +++ b/scripts/check_joss_artifacts.py @@ -0,0 +1,72 @@ +"""Check submission artifacts, not editorial eligibility. Requires PyYAML.""" +from pathlib import Path +import argparse +import json +import re +import sys +import yaml + +ROOT = Path(__file__).resolve().parents[1] +REQUIRED = ["Summary", "Statement of need", "State of the field", "Software design", + "Research impact statement", "AI usage disclosure", "Acknowledgements", "References"] + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--submission", action="store_true", help="also fail on outstanding author/history records") + args = parser.parse_args() + errors = [] + record = json.loads((ROOT / "docs/joss/submission-record.json").read_text(encoding="utf-8")) + paper = (ROOT / "paper/paper.md").read_text(encoding="utf-8") + _, header, body = paper.split("---", 2) + meta = yaml.safe_load(header) + author = record["author"] + expected = {"name": author["name"], "orcid": author["orcid"], "email": author["email"]} + if len(meta.get("authors", [])) != 1: + errors.append("Expected the confirmed sole author") + else: + for key, value in expected.items(): + if str(meta["authors"][0].get(key)) != value: + errors.append("Author mismatch: " + key) + if not any(a.get("name") == author["affiliation"] for a in meta.get("affiliations", [])): + errors.append("Affiliation does not match the confirmed record") + for heading in REQUIRED: + if "# " + heading + "\n" not in body: + errors.append("Missing section: " + heading) + bib = (ROOT / "paper/paper.bib").read_text(encoding="utf-8") + keys = set(re.findall(r"@\w+\s*\{\s*([^,]+),", bib)) + cited = set(re.findall(r"(?