PTS-WFM4Cities 3.0.0__tar.gz

pts_wfm4cities-3.0.0/AUTHORS.md

@@ -0,0 +1,14 @@
+# Authors and maintainers
+
+WFM4Cities was developed by:
+
+- Zuo Zhang (张祚), Central China Normal University;
+- Yukun Jiang (江驭鲲);
+- Zhe Wang (王哲).
+
+The public contact retained from the existing PyPI release is
+`jiangyukunccnu@163.com`.
+
+Contributors should be acknowledged through the Git history and release notes.
+Please do not add an affiliation, email address, ORCID, or contributor role
+without confirmation from the person concerned.

pts_wfm4cities-3.0.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes follow the principles of
+[Keep a Changelog](https://keepachangelog.com/) and semantic versioning.
+
+## [3.0.0] - 2026-08-08
+
+### Added
+
+- import-safe lowercase `wfm4cities` package;
+- validated point-pattern and point-to-surface API;
+- cubic interpolation with nearest-neighbor boundary filling;
+- explicit 51-level PTS implementation for A(h), V(h), N(h), and L(h);
+- fixed ten-feature extraction used by the associated study;
+- headless `demo`, `points`, and `scan` commands;
+- single-window bilingual Tk interface with threshold animation;
+- CSV/JSON exports and reproducible overview figures;
+- optional GeoPandas/PySAL Moran diagnostic;
+- tests, CI, trusted-publishing workflow, citation metadata, and release guide;
+- compatibility namespace and command for 2.x users;
+- unmodified 2.6 single-file script in `legacy/` for provenance.
+
+### Changed
+
+- internal code is separated into numerical, PTS, I/O, plotting, optional
+  spatial, CLI, and GUI modules;
+- supported Python is now 3.10--3.13;
+- runtime dependencies use compatible ranges rather than exact historical pins;
+- the canonical version is consistently 3.0.0;
+- the PyPI distribution is published as `PTS-WFM4Cities`; the historical 2.6
+  release stays under the shorter name `WFM4Cities`.
+
+### Fixed
+
+- importing the package no longer creates Tk roots or starts a main loop;
+- Matplotlib's backend and system font are no longer changed at import time;
+- the PyPI homepage points to the real GitHub repository;
+- CLI routing no longer depends on GUI global variables;
+- impossible cluster-center settings fail with an actionable error;
+- distribution metadata now includes the license, README, source distribution,
+  wheel, and citation information.
+
+## [2.6] - 2025-01-22
+
+- historical PyPI release containing the original desktop script.
+
+[3.0.0]: https://github.com/zhangzuocughustccnu/WFM4Cities/releases/tag/v3.0.0

pts_wfm4cities-3.0.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use WFM4Cities, please cite this software and the associated article when available."
+title: "WFM4Cities: DEM-inspired urban scalar surfaces and progressive threshold scanning"
+type: software
+version: 3.0.0
+date-released: 2026-08-08
+license: MIT
+repository-code: "https://github.com/zhangzuocughustccnu/WFM4Cities"
+url: "https://github.com/zhangzuocughustccnu/WFM4Cities"
+keywords:
+  - urban morphology
+  - progressive threshold scanning
+  - scalar surface
+  - spatial analysis
+authors:
+  - family-names: Zhang
+    given-names: Zuo
+    affiliation: Central China Normal University
+  - family-names: Jiang
+    given-names: Yukun
+  - family-names: Wang
+    given-names: Zhe

pts_wfm4cities-3.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Community conduct
+
+Project participation should be professional, respectful, and focused on
+scientific and software quality.
+
+Acceptable participation includes constructive review, clear attribution,
+reproducible evidence, and good-faith disagreement. Harassment, discrimination,
+personal attacks, deliberate misrepresentation, plagiarism, and disclosure of
+private information are not acceptable.
+
+Maintainers may edit or remove material that violates these expectations and
+may restrict repeated disruptive participation. Concerns should be reported
+privately through the contact route in SECURITY.md.

pts_wfm4cities-3.0.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Thank you for helping improve WFM4Cities.
+
+## Before opening a change
+
+1. Search existing issues.
+2. For method changes, state the mathematical convention being changed and why.
+3. Do not silently change threshold inequalities, connectivity, normalization,
+   interpolation, random seeds, or output field names.
+4. Add or update tests for every behavior change.
+
+## Development setup
+
+    python -m venv .venv
+    source .venv/bin/activate
+    python -m pip install -e ".[dev]"
+
+Use `.venv\Scripts\Activate.ps1` on Windows PowerShell.
+
+Run:
+
+    ruff check .
+    pytest
+    python -m build
+    python -m twine check dist/*
+
+## Pull requests
+
+- keep each pull request focused;
+- explain scientific and software consequences;
+- update CHANGELOG.md for user-visible changes;
+- preserve backwards compatibility where practical;
+- do not commit generated environments, caches, credentials, or large
+  unpublished research data;
+- confirm that you have the right to contribute all included code and data.
+
+## Reproducible bug reports
+
+Include operating system, Python version, WFM4Cities version, installation
+command, minimal input or script, full error message, and expected behavior.

pts_wfm4cities-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zuo Zhang, Yukun Jiang, and Zhe Wang
+
+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.

pts_wfm4cities-3.0.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include LICENSE
+include README.md
+include README_zh-CN.md
+include CHANGELOG.md
+include CITATION.cff
+include AUTHORS.md
+include WFM4Cities.py
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include MIGRATION.md
+include SECURITY.md
+include THIRD_PARTY_NOTICES.md
+include environment.yml
+include requirements*.txt
+recursive-include docs *.md
+recursive-include examples *.py *.csv *.md
+recursive-include src *.py py.typed
+prune legacy

pts_wfm4cities-3.0.0/MIGRATION.md

@@ -0,0 +1,39 @@
+# Migrating from WFM4Cities 2.6 to 3.0
+
+## What remains compatible
+
+- distribution name: `WFM4Cities`;
+- historical command: `WFM4Cities`;
+- historical module path: `WFM4Cities.Water_flooding_Model`;
+- top-level launcher: `python WFM4Cities.py`.
+
+Each now forwards to maintained code.
+
+## Recommended new usage
+
+Use lowercase imports:
+
+    import wfm4cities
+
+Launch the interface with:
+
+    wfm4cities gui
+
+Run reproducible analyses without a display:
+
+    wfm4cities demo
+    wfm4cities points observations.csv
+    wfm4cities scan surface.csv
+
+## Intentional changes
+
+- No window opens during import.
+- No Matplotlib backend is forced during import.
+- Random generation uses a local `numpy.random.Generator` with an explicit
+  seed.
+- Cubic interpolation boundaries are filled by nearest-neighbor values.
+- PTS metrics and threshold rules are explicit and independently callable.
+- Heavy GeoPandas/PySAL dependencies are optional.
+
+The historical script is in `legacy/WFM4Cities_2.6_original.py`. It is not
+imported, tested, or installed.

pts_wfm4cities-3.0.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: PTS-WFM4Cities
+Version: 3.0.0
+Summary: DEM-inspired urban scalar surfaces and progressive threshold scanning
+Author: Zuo Zhang, Zhe Wang
+Author-email: Yukun Jiang <jiangyukunccnu@163.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zhangzuocughustccnu/WFM4Cities
+Project-URL: Repository, https://github.com/zhangzuocughustccnu/WFM4Cities.git
+Project-URL: Issues, https://github.com/zhangzuocughustccnu/WFM4Cities/issues
+Project-URL: Changelog, https://github.com/zhangzuocughustccnu/WFM4Cities/blob/main/CHANGELOG.md
+Keywords: urban morphology,progressive threshold scanning,scalar surface,spatial analysis,DEM-inspired
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: scipy<2,>=1.10
+Requires-Dist: matplotlib<4,>=3.7
+Requires-Dist: scikit-learn<2,>=1.3
+Provides-Extra: spatial
+Requires-Dist: geopandas<2,>=0.13; extra == "spatial"
+Requires-Dist: shapely<3,>=2; extra == "spatial"
+Requires-Dist: libpysal<5,>=4.9; extra == "spatial"
+Requires-Dist: esda<3,>=2.5; extra == "spatial"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# WFM4Cities
+
+[![CI](https://github.com/zhangzuocughustccnu/WFM4Cities/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangzuocughustccnu/WFM4Cities/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/PTS-WFM4Cities.svg)](https://pypi.org/project/PTS-WFM4Cities/)
+[![Python](https://img.shields.io/pypi/pyversions/PTS-WFM4Cities.svg)](https://pypi.org/project/PTS-WFM4Cities/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+WFM4Cities is a research-oriented Python package for constructing DEM-inspired
+urban scalar surfaces and analyzing them with Progressive Threshold Scanning
+(PTS). It supports a transparent point-to-surface workflow, a headless API and
+command-line interface, and an optional bilingual desktop interface.
+
+[简体中文说明](README_zh-CN.md)
+
+## What the package does
+
+- checks and visualizes point patterns;
+- interpolates scattered observations with
+  `scipy.interpolate.griddata(method="cubic")`;
+- fills cells outside the cubic interpolation hull with nearest-neighbor values;
+- min--max normalizes an analytical surface to \([0,1]\);
+- scans an ordered threshold sequence;
+- calculates projected area \(A(h)\), normalized excess volume \(V(h)\),
+  connected-component count \(N(h)\), and largest-component ratio \(L(h)\);
+- exports regular grids, full response trajectories, fixed summary features,
+  and overview figures;
+- provides optional GeoPandas/PySAL spatial diagnostics.
+
+WFM4Cities treats the vertical coordinate as the value of a specified urban
+attribute (for example, density, activity intensity, or building volume). It
+does **not** infer the meaning of that variable.
+
+## Scientific scope
+
+The water-flooding metaphor is an explanatory analogy for moving a horizontal
+threshold through a scalar surface. WFM4Cities is **not** a hydrodynamic flood
+model, a general DEM-production system, or an operational planning platform.
+Threshold order is not time. Hydrological applications require additional
+terrain, rainfall, drainage, flow-path, water-depth, and exposure information.
+
+## Installation
+
+Python 3.10--3.13 is supported. Python 3.11 is the recommended reference
+environment.
+
+### Install from the repository
+
+    git clone https://github.com/zhangzuocughustccnu/WFM4Cities.git
+    cd WFM4Cities
+    python -m venv .venv
+
+Activate the environment:
+
+    # Windows PowerShell
+    .venv\Scripts\Activate.ps1
+
+    # macOS/Linux
+    source .venv/bin/activate
+
+Then install:
+
+    python -m pip install --upgrade pip
+    python -m pip install -e .
+
+### Install the released package
+
+    python -m pip install PTS-WFM4Cities
+
+The PyPI distribution is named `PTS-WFM4Cities`. The historical 2.6 release is
+still published under the shorter name `WFM4Cities`, which belongs to a
+different PyPI account, so `pip install WFM4Cities` installs that older
+release. Always install `PTS-WFM4Cities` to get version 3.0.
+
+### Optional spatial diagnostics
+
+    python -m pip install "PTS-WFM4Cities[spatial]"
+
+### Conda environment
+
+    conda env create -f environment.yml
+    conda activate wfm4cities-3.0
+
+Tkinter is included with standard Python on Windows and macOS. On some Linux
+distributions it is a separate operating-system package (for example,
+`sudo apt install python3-tk` on Debian/Ubuntu).
+
+## Quick start
+
+### Desktop interface
+
+    wfm4cities gui
+
+Running `wfm4cities` with no subcommand also opens the interface. The
+historical `WFM4Cities` command remains available after installation; the
+`python WFM4Cities.py` launcher also remains available in a source checkout.
+
+### Deterministic headless demonstration
+
+    wfm4cities demo --output-dir demo_results --seed 42
+
+This writes:
+
+- `source_points.csv`;
+- `surface_normalized.csv`;
+- `pts_response.csv`;
+- `pts_features.json`;
+- `wfm4cities_overview.png`.
+
+### Analyze an existing grid
+
+The input must be a headerless numeric CSV matrix:
+
+    wfm4cities scan my_surface.csv --output-dir scan_results
+
+Use strict thresholding to exclude zero background cells at \(h=0\):
+
+    wfm4cities scan my_surface.csv --rule strict --output-dir scan_results
+
+### Construct a surface from points
+
+The CSV must contain `x` and `y` columns. An optional column named
+`value`, `density`, or `z` supplies the vertical value. If it is absent,
+WFM4Cities calculates a local neighbor count.
+
+    wfm4cities points observations.csv --grid-size 100 --method cubic
+
+## Python API
+
+    from wfm4cities import (
+        SimulationConfig,
+        build_surface,
+        extract_features,
+        progressive_threshold_scan,
+    )
+
+    config = SimulationConfig(
+        num_points=150,
+        noise_ratio=0.30,
+        num_clusters=4,
+        grid_size=100,
+        seed=2026,
+    )
+    model = build_surface(config)
+    result = progressive_threshold_scan(
+        model.grid_z,
+        threshold_count=51,
+        threshold_min=0.0,
+        threshold_max=0.95,
+        rule="inclusive",
+        connectivity=8,
+    )
+    features = extract_features(result)
+    print(features)
+
+The main response arrays are available as `result.A`, `result.V`,
+`result.N`, and `result.L`.
+
+## Threshold conventions
+
+Two explicit rules are available:
+
+- `inclusive`: retain cells satisfying \(z \ge h\). This is the default and
+  matches the controlled archetype analysis.
+- `strict`: retain cells satisfying \(z > h\). This excludes zero-valued
+  background cells when \(h=0\).
+
+The denominator of \(A(h)\) is the fixed analysis domain, not the number of
+currently positive cells. Components use eight-neighbor connectivity by
+default; four-neighbor connectivity is also available. \(V(h)\) is normalized
+by total intensity at \(h=0\).
+
+See [Method conventions](docs/METHOD.md) for the exact definitions.
+
+## Project structure
+
+    WFM4Cities/
+    ├── src/wfm4cities/       # maintained implementation
+    ├── src/WFM4Cities/       # compatibility namespace for 2.x users
+    ├── tests/                # automated regression tests
+    ├── examples/             # executable examples and sample data
+    ├── docs/                 # method, API, architecture, and release notes
+    ├── legacy/               # unmodified historical single-file script
+    ├── pyproject.toml        # package metadata and dependencies
+    ├── environment.yml       # recommended Conda environment
+    ├── CITATION.cff          # machine-readable software citation
+    └── LICENSE               # MIT license
+
+The maintained package does not create Tk windows or force a Matplotlib backend
+when imported. GUI code is loaded only when requested.
+
+## Reproducibility and testing
+
+Create a development environment and run:
+
+    python -m pip install -e ".[dev]"
+    ruff check .
+    pytest
+    python -m build
+    python -m twine check dist/*
+
+`requirements-tested.txt` records the exact numerical library versions used
+for the 3.0.0 release-candidate verification. `pyproject.toml` remains the
+authoritative dependency specification.
+
+## Method demonstration
+
+The physical immersion demonstration used to explain the threshold analogy is
+available at [YouTube](https://youtu.be/tMdRVbR-JpQ). It is explanatory only
+and does not define the numerical algorithm.
+
+## Authors
+
+WFM4Cities was developed by **Zuo Zhang, Yukun Jiang, and Zhe Wang**.
+See [AUTHORS.md](AUTHORS.md) for details.
+
+## Citation
+
+Use GitHub's “Cite this repository” control or the metadata in
+[CITATION.cff](CITATION.cff). Add the article DOI to the citation metadata after
+the associated paper is published; no DOI is invented in this repository.
+
+## Contributing and support
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request.
+Reproducible bug reports can be filed through the repository's issue templates.
+Security-sensitive reports should follow [SECURITY.md](SECURITY.md).
+
+## License
+
+WFM4Cities is distributed under the [MIT License](LICENSE). The historical
+script is retained for provenance and is covered by the same repository license.