geoai3d 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- geoai3d-0.0.1/.github/ISSUE_TEMPLATE/bug_report.yml +45 -0
- geoai3d-0.0.1/.github/ISSUE_TEMPLATE/config.yml +8 -0
- geoai3d-0.0.1/.github/ISSUE_TEMPLATE/feature_request.yml +39 -0
- geoai3d-0.0.1/.github/PULL_REQUEST_TEMPLATE.md +22 -0
- geoai3d-0.0.1/.github/dependabot.yml +10 -0
- geoai3d-0.0.1/.github/workflows/ci.yml +69 -0
- geoai3d-0.0.1/.github/workflows/docs.yml +36 -0
- geoai3d-0.0.1/.gitignore +25 -0
- geoai3d-0.0.1/.pre-commit-config.yaml +17 -0
- geoai3d-0.0.1/AI_USAGE.md +28 -0
- geoai3d-0.0.1/CHANGELOG.md +24 -0
- geoai3d-0.0.1/CITATION.cff +29 -0
- geoai3d-0.0.1/CODE_OF_CONDUCT.md +79 -0
- geoai3d-0.0.1/CONTRIBUTING.md +114 -0
- geoai3d-0.0.1/LICENSE +21 -0
- geoai3d-0.0.1/PKG-INFO +154 -0
- geoai3d-0.0.1/README.md +116 -0
- geoai3d-0.0.1/SECURITY.md +20 -0
- geoai3d-0.0.1/SUPPORT.md +29 -0
- geoai3d-0.0.1/docs/contributing.md +114 -0
- geoai3d-0.0.1/docs/index.md +41 -0
- geoai3d-0.0.1/mkdocs.yml +43 -0
- geoai3d-0.0.1/pyproject.toml +114 -0
- geoai3d-0.0.1/src/geoai3d/__init__.py +9 -0
- geoai3d-0.0.1/src/geoai3d/py.typed +0 -0
- geoai3d-0.0.1/tests/test_package.py +20 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: Something does not work as documented
|
|
3
|
+
labels: ["bug", "triage"]
|
|
4
|
+
body:
|
|
5
|
+
- type: textarea
|
|
6
|
+
id: what-happened
|
|
7
|
+
attributes:
|
|
8
|
+
label: What happened
|
|
9
|
+
description: What you expected, and what occurred instead.
|
|
10
|
+
validations:
|
|
11
|
+
required: true
|
|
12
|
+
- type: textarea
|
|
13
|
+
id: reproduce
|
|
14
|
+
attributes:
|
|
15
|
+
label: Minimal reproducible example
|
|
16
|
+
description: The smallest code that shows the problem.
|
|
17
|
+
render: python
|
|
18
|
+
validations:
|
|
19
|
+
required: true
|
|
20
|
+
- type: textarea
|
|
21
|
+
id: traceback
|
|
22
|
+
attributes:
|
|
23
|
+
label: Full traceback
|
|
24
|
+
render: shell
|
|
25
|
+
- type: input
|
|
26
|
+
id: version
|
|
27
|
+
attributes:
|
|
28
|
+
label: geoai3d version
|
|
29
|
+
description: "Output of: python -c \"import geoai3d; print(geoai3d.__version__)\""
|
|
30
|
+
validations:
|
|
31
|
+
required: true
|
|
32
|
+
- type: input
|
|
33
|
+
id: environment
|
|
34
|
+
attributes:
|
|
35
|
+
label: OS, Python version, and install method
|
|
36
|
+
placeholder: "macOS 15.2, Python 3.12, pip install geoai3d"
|
|
37
|
+
validations:
|
|
38
|
+
required: true
|
|
39
|
+
- type: textarea
|
|
40
|
+
id: data
|
|
41
|
+
attributes:
|
|
42
|
+
label: Data characteristics
|
|
43
|
+
description: >-
|
|
44
|
+
If the problem involves a point cloud: format, approximate point count,
|
|
45
|
+
horizontal and vertical CRS. Do not upload large or sensitive files.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
blank_issues_enabled: true
|
|
2
|
+
contact_links:
|
|
3
|
+
- name: Question or discussion
|
|
4
|
+
url: https://github.com/agelamin17/geoai3d/discussions
|
|
5
|
+
about: Ask usage questions or discuss direction here rather than in issues.
|
|
6
|
+
- name: Security vulnerability
|
|
7
|
+
url: https://github.com/agelamin17/geoai3d/security/advisories/new
|
|
8
|
+
about: Report privately. Please do not open a public issue.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
name: Feature request
|
|
2
|
+
description: Suggest a capability
|
|
3
|
+
labels: ["enhancement", "triage"]
|
|
4
|
+
body:
|
|
5
|
+
- type: textarea
|
|
6
|
+
id: problem
|
|
7
|
+
attributes:
|
|
8
|
+
label: The problem
|
|
9
|
+
description: >-
|
|
10
|
+
Describe the workflow you are trying to complete and where it currently
|
|
11
|
+
breaks down. Focus on the problem rather than a proposed API.
|
|
12
|
+
validations:
|
|
13
|
+
required: true
|
|
14
|
+
- type: textarea
|
|
15
|
+
id: current
|
|
16
|
+
attributes:
|
|
17
|
+
label: How you handle it today
|
|
18
|
+
description: Which tools, and what makes that unsatisfactory.
|
|
19
|
+
- type: dropdown
|
|
20
|
+
id: domain
|
|
21
|
+
attributes:
|
|
22
|
+
label: Application domain
|
|
23
|
+
options:
|
|
24
|
+
- Airborne Lidar / topographic mapping
|
|
25
|
+
- Terrestrial or mobile laser scanning
|
|
26
|
+
- UAV photogrammetry
|
|
27
|
+
- Forestry
|
|
28
|
+
- Surveying / engineering
|
|
29
|
+
- Bathymetry
|
|
30
|
+
- Geomorphology / change detection
|
|
31
|
+
- Cultural heritage
|
|
32
|
+
- Other
|
|
33
|
+
- type: textarea
|
|
34
|
+
id: licensing
|
|
35
|
+
attributes:
|
|
36
|
+
label: Relevant prior art
|
|
37
|
+
description: >-
|
|
38
|
+
Papers or open-source implementations. Please note the licence of anything
|
|
39
|
+
you link, so we can check compatibility with an MIT core early.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
## Summary
|
|
2
|
+
|
|
3
|
+
<!-- What this changes and why. Reference an issue where one exists. -->
|
|
4
|
+
|
|
5
|
+
## Checklist
|
|
6
|
+
|
|
7
|
+
- [ ] Tests added or updated, and `pytest -m "not gpu"` passes locally
|
|
8
|
+
- [ ] `ruff check .`, `ruff format --check .`, and `mypy` pass
|
|
9
|
+
- [ ] Public functions have type hints and Google-style docstrings with a runnable example
|
|
10
|
+
- [ ] Spatial outputs carry a CRS; no silent datum assumptions introduced
|
|
11
|
+
- [ ] CHANGELOG.md updated under `Unreleased`
|
|
12
|
+
- [ ] No new base dependency, or the addition is justified below
|
|
13
|
+
|
|
14
|
+
## Licensing
|
|
15
|
+
|
|
16
|
+
- [ ] I have the right to contribute this code under MIT
|
|
17
|
+
- [ ] No code copied from proprietary or copyleft-incompatible sources
|
|
18
|
+
- [ ] Any new dependency's licence is compatible with an MIT core (state it below)
|
|
19
|
+
|
|
20
|
+
## AI assistance
|
|
21
|
+
|
|
22
|
+
<!-- Which tools were used, and for what. Write "none" if none. -->
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
concurrency:
|
|
10
|
+
group: ${{ github.workflow }}-${{ github.ref }}
|
|
11
|
+
cancel-in-progress: true
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
lint:
|
|
18
|
+
name: Lint and type-check
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v7
|
|
22
|
+
- uses: actions/setup-python@v7
|
|
23
|
+
with:
|
|
24
|
+
python-version: "3.12"
|
|
25
|
+
- run: python -m pip install --upgrade pip
|
|
26
|
+
- run: pip install -e ".[dev]"
|
|
27
|
+
- run: ruff check .
|
|
28
|
+
- run: ruff format --check .
|
|
29
|
+
- run: mypy
|
|
30
|
+
|
|
31
|
+
test:
|
|
32
|
+
name: Test ${{ matrix.os }} / Python ${{ matrix.python-version }}
|
|
33
|
+
runs-on: ${{ matrix.os }}
|
|
34
|
+
strategy:
|
|
35
|
+
fail-fast: false
|
|
36
|
+
matrix:
|
|
37
|
+
os: [ubuntu-latest, macos-latest, windows-latest]
|
|
38
|
+
python-version: ["3.10", "3.11", "3.12", "3.13"]
|
|
39
|
+
steps:
|
|
40
|
+
- uses: actions/checkout@v7
|
|
41
|
+
- uses: actions/setup-python@v7
|
|
42
|
+
with:
|
|
43
|
+
python-version: ${{ matrix.python-version }}
|
|
44
|
+
- run: python -m pip install --upgrade pip
|
|
45
|
+
- run: pip install -e ".[dev]"
|
|
46
|
+
- run: pytest -m "not gpu" --cov --cov-report=xml
|
|
47
|
+
|
|
48
|
+
build:
|
|
49
|
+
name: Build distribution
|
|
50
|
+
runs-on: ubuntu-latest
|
|
51
|
+
steps:
|
|
52
|
+
- uses: actions/checkout@v7
|
|
53
|
+
- uses: actions/setup-python@v7
|
|
54
|
+
with:
|
|
55
|
+
python-version: "3.12"
|
|
56
|
+
- run: pip install build twine
|
|
57
|
+
- run: python -m build
|
|
58
|
+
- run: twine check dist/*
|
|
59
|
+
|
|
60
|
+
cpu-only-install:
|
|
61
|
+
name: Bare install, no compiler
|
|
62
|
+
runs-on: ubuntu-latest
|
|
63
|
+
container: python:3.12-slim
|
|
64
|
+
steps:
|
|
65
|
+
- uses: actions/checkout@v7
|
|
66
|
+
- name: Install from source with no build toolchain present
|
|
67
|
+
run: pip install .
|
|
68
|
+
- name: Import on a machine with no GPU and no compiler
|
|
69
|
+
run: python -c "import geoai3d; print(geoai3d.__version__)"
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: Docs
|
|
2
|
+
|
|
3
|
+
# Manual-only until Stage 2, when the documentation site has real content and
|
|
4
|
+
# GitHub Pages is enabled (Settings -> Pages -> Source: GitHub Actions). Re-add
|
|
5
|
+
# the push trigger then. Run on demand from the Actions tab in the meantime.
|
|
6
|
+
on:
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
permissions:
|
|
10
|
+
contents: read
|
|
11
|
+
pages: write
|
|
12
|
+
id-token: write
|
|
13
|
+
|
|
14
|
+
concurrency:
|
|
15
|
+
group: pages
|
|
16
|
+
cancel-in-progress: false
|
|
17
|
+
|
|
18
|
+
jobs:
|
|
19
|
+
build-and-deploy:
|
|
20
|
+
runs-on: ubuntu-latest
|
|
21
|
+
environment:
|
|
22
|
+
name: github-pages
|
|
23
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
24
|
+
steps:
|
|
25
|
+
- uses: actions/checkout@v7
|
|
26
|
+
- uses: actions/setup-python@v7
|
|
27
|
+
with:
|
|
28
|
+
python-version: "3.12"
|
|
29
|
+
- run: pip install -e ".[docs]"
|
|
30
|
+
- run: mkdocs build --strict
|
|
31
|
+
- uses: actions/configure-pages@v6
|
|
32
|
+
- uses: actions/upload-pages-artifact@v5
|
|
33
|
+
with:
|
|
34
|
+
path: site
|
|
35
|
+
- id: deployment
|
|
36
|
+
uses: actions/deploy-pages@v5
|
geoai3d-0.0.1/.gitignore
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
*.egg-info/
|
|
4
|
+
build/
|
|
5
|
+
dist/
|
|
6
|
+
.venv/
|
|
7
|
+
venv/
|
|
8
|
+
.env
|
|
9
|
+
.pytest_cache/
|
|
10
|
+
.ruff_cache/
|
|
11
|
+
.mypy_cache/
|
|
12
|
+
.coverage
|
|
13
|
+
htmlcov/
|
|
14
|
+
coverage.xml
|
|
15
|
+
site/
|
|
16
|
+
.ipynb_checkpoints/
|
|
17
|
+
.DS_Store
|
|
18
|
+
.idea/
|
|
19
|
+
.vscode/
|
|
20
|
+
*.las
|
|
21
|
+
*.laz
|
|
22
|
+
*.e57
|
|
23
|
+
*.ply
|
|
24
|
+
*.pcd
|
|
25
|
+
!tests/data/*.laz
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
repos:
|
|
2
|
+
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
3
|
+
rev: v5.0.0
|
|
4
|
+
hooks:
|
|
5
|
+
- id: trailing-whitespace
|
|
6
|
+
- id: end-of-file-fixer
|
|
7
|
+
- id: check-yaml
|
|
8
|
+
- id: check-toml
|
|
9
|
+
- id: check-added-large-files
|
|
10
|
+
args: ["--maxkb=1024"]
|
|
11
|
+
- id: check-merge-conflict
|
|
12
|
+
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
13
|
+
rev: v0.8.4
|
|
14
|
+
hooks:
|
|
15
|
+
- id: ruff
|
|
16
|
+
args: [--fix]
|
|
17
|
+
- id: ruff-format
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# AI Usage Disclosure
|
|
2
|
+
|
|
3
|
+
This project uses generative AI assistance in development. This file is a running
|
|
4
|
+
record, maintained as work happens rather than reconstructed later, so that any
|
|
5
|
+
future publication or review has an accurate account.
|
|
6
|
+
|
|
7
|
+
Journals including JOSS require a disclosure covering the tools used, where they
|
|
8
|
+
were used, the nature and scope of assistance, and confirmation that human authors
|
|
9
|
+
reviewed and validated the output and made the core design decisions.
|
|
10
|
+
|
|
11
|
+
## Standing statement
|
|
12
|
+
|
|
13
|
+
All AI-assisted output in this repository has been reviewed, edited, and validated
|
|
14
|
+
by the maintainer. Problem framing, architectural decisions, dependency and
|
|
15
|
+
licensing choices, and the project roadmap are human decisions.
|
|
16
|
+
|
|
17
|
+
## Log
|
|
18
|
+
|
|
19
|
+
| Date | Tool / model | Where | Nature and scope |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| 2026-07-21 | Claude (Anthropic) | Repository scaffolding, docs | Drafted the project skeleton: packaging configuration, CI workflows, README, contributing and support documentation. Reviewed and edited by the maintainer. |
|
|
22
|
+
| 2026-07-21 | Claude (Anthropic) | Planning | Assisted in drafting the staged development roadmap and reviewing submission requirements. Strategic decisions made by the maintainer. |
|
|
23
|
+
|
|
24
|
+
## For contributors
|
|
25
|
+
|
|
26
|
+
Disclose AI assistance in your pull request description — which tools, and for
|
|
27
|
+
what. Accepted contributions are added to the log above. You remain responsible
|
|
28
|
+
for the correctness, originality, and licensing of what you submit.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here.
|
|
4
|
+
|
|
5
|
+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- Nothing yet. Stage 1 work begins here.
|
|
12
|
+
|
|
13
|
+
## [0.0.1] - 2026-07-21
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- Project skeleton: packaging, licence, and documentation scaffolding.
|
|
17
|
+
- Continuous integration across Linux, macOS, and Windows on Python 3.10 to 3.13.
|
|
18
|
+
- A dedicated CI job verifying that the base install succeeds in a container with
|
|
19
|
+
no compiler and no GPU.
|
|
20
|
+
- Linting, formatting, and strict type checking via ruff and mypy.
|
|
21
|
+
- Contribution, support, governance, and AI usage documentation.
|
|
22
|
+
|
|
23
|
+
[Unreleased]: https://github.com/agelamin17/geoai3d/compare/v0.0.1...HEAD
|
|
24
|
+
[0.0.1]: https://github.com/agelamin17/geoai3d/releases/tag/v0.0.1
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
title: "GEOAI_3D: geospatial-first AI workflows for 3D data"
|
|
3
|
+
message: "If you use this software, please cite it using these metadata."
|
|
4
|
+
type: software
|
|
5
|
+
authors:
|
|
6
|
+
- given-names: Ahmed
|
|
7
|
+
family-names: Elamin
|
|
8
|
+
email: agelamin@outlook.com
|
|
9
|
+
# orcid: "https://orcid.org/0000-0000-0000-0000"
|
|
10
|
+
repository-code: "https://github.com/agelamin17/geoai3d"
|
|
11
|
+
url: "https://github.com/agelamin17/geoai3d"
|
|
12
|
+
abstract: >-
|
|
13
|
+
GEOAI_3D provides high-level, geospatial-first AI workflows for
|
|
14
|
+
three-dimensional data, including Lidar point clouds, photogrammetric
|
|
15
|
+
reconstruction, and Gaussian splatting. Coordinate reference systems,
|
|
16
|
+
vertical datums, uncertainty, and provenance are treated as first-class
|
|
17
|
+
properties of the data rather than optional metadata.
|
|
18
|
+
keywords:
|
|
19
|
+
- lidar
|
|
20
|
+
- point cloud
|
|
21
|
+
- geospatial
|
|
22
|
+
- remote sensing
|
|
23
|
+
- photogrammetry
|
|
24
|
+
- geomatics
|
|
25
|
+
- Gaussian splatting
|
|
26
|
+
- deep learning
|
|
27
|
+
license: MIT
|
|
28
|
+
version: 0.0.1
|
|
29
|
+
date-released: "2026-07-21"
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Contributor Covenant Code of Conduct
|
|
2
|
+
|
|
3
|
+
## Our Pledge
|
|
4
|
+
|
|
5
|
+
We as members, contributors, and leaders pledge to make participation in our
|
|
6
|
+
community a harassment-free experience for everyone, regardless of age, body size,
|
|
7
|
+
visible or invisible disability, ethnicity, sex characteristics, gender identity
|
|
8
|
+
and expression, level of experience, education, socio-economic status,
|
|
9
|
+
nationality, personal appearance, race, caste, colour, religion, or sexual
|
|
10
|
+
identity and orientation.
|
|
11
|
+
|
|
12
|
+
We pledge to act and interact in ways that contribute to an open, welcoming,
|
|
13
|
+
diverse, inclusive, and healthy community.
|
|
14
|
+
|
|
15
|
+
## Our Standards
|
|
16
|
+
|
|
17
|
+
Examples of behaviour that contributes to a positive environment include:
|
|
18
|
+
|
|
19
|
+
* Demonstrating empathy and kindness toward other people
|
|
20
|
+
* Being respectful of differing opinions, viewpoints, and experiences
|
|
21
|
+
* Giving and gracefully accepting constructive feedback
|
|
22
|
+
* Accepting responsibility and apologising to those affected by our mistakes,
|
|
23
|
+
and learning from the experience
|
|
24
|
+
* Focusing on what is best not just for us as individuals, but for the overall
|
|
25
|
+
community
|
|
26
|
+
|
|
27
|
+
Examples of unacceptable behaviour include:
|
|
28
|
+
|
|
29
|
+
* The use of sexualised language or imagery, and sexual attention or advances of
|
|
30
|
+
any kind
|
|
31
|
+
* Trolling, insulting or derogatory comments, and personal or political attacks
|
|
32
|
+
* Public or private harassment
|
|
33
|
+
* Publishing others' private information, such as a physical or email address,
|
|
34
|
+
without their explicit permission
|
|
35
|
+
* Other conduct which could reasonably be considered inappropriate in a
|
|
36
|
+
professional setting
|
|
37
|
+
|
|
38
|
+
## Enforcement Responsibilities
|
|
39
|
+
|
|
40
|
+
Community leaders are responsible for clarifying and enforcing our standards of
|
|
41
|
+
acceptable behaviour and will take appropriate and fair corrective action in
|
|
42
|
+
response to any behaviour that they deem inappropriate, threatening, offensive,
|
|
43
|
+
or harmful.
|
|
44
|
+
|
|
45
|
+
Community leaders have the right and responsibility to remove, edit, or reject
|
|
46
|
+
comments, commits, code, wiki edits, issues, and other contributions that are not
|
|
47
|
+
aligned to this Code of Conduct, and will communicate reasons for moderation
|
|
48
|
+
decisions when appropriate.
|
|
49
|
+
|
|
50
|
+
## Scope
|
|
51
|
+
|
|
52
|
+
This Code of Conduct applies within all community spaces, and also applies when
|
|
53
|
+
an individual is officially representing the community in public spaces.
|
|
54
|
+
|
|
55
|
+
## Enforcement
|
|
56
|
+
|
|
57
|
+
Instances of abusive, harassing, or otherwise unacceptable behaviour may be
|
|
58
|
+
reported to the community leaders responsible for enforcement at
|
|
59
|
+
agelamin@outlook.com. All complaints will be reviewed and investigated promptly
|
|
60
|
+
and fairly.
|
|
61
|
+
|
|
62
|
+
All community leaders are obligated to respect the privacy and security of the
|
|
63
|
+
reporter of any incident.
|
|
64
|
+
|
|
65
|
+
## Attribution
|
|
66
|
+
|
|
67
|
+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
|
68
|
+
version 2.1, available at
|
|
69
|
+
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
|
|
70
|
+
|
|
71
|
+
Community Impact Guidelines were inspired by
|
|
72
|
+
[Mozilla's code of conduct enforcement ladder][mozilla].
|
|
73
|
+
|
|
74
|
+
[homepage]: https://www.contributor-covenant.org
|
|
75
|
+
[mozilla]: https://github.com/mozilla/diversity
|
|
76
|
+
|
|
77
|
+
For answers to common questions about this code of conduct, see the FAQ at
|
|
78
|
+
https://www.contributor-covenant.org/faq. Translations are available at
|
|
79
|
+
https://www.contributor-covenant.org/translations.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Contributing to GEOAI_3D
|
|
2
|
+
|
|
3
|
+
Contributions are welcome at any scale, from a typo fix to a new module. This
|
|
4
|
+
document covers how to work on the code and the few rules that are not negotiable.
|
|
5
|
+
|
|
6
|
+
## Ways to help that are not code
|
|
7
|
+
|
|
8
|
+
The project needs these at least as much as it needs pull requests:
|
|
9
|
+
|
|
10
|
+
- **Test data.** Point clouds with known, independently surveyed control. This is
|
|
11
|
+
the scarcest resource in the project.
|
|
12
|
+
- **Workflow reports.** Tell us what you do with 3D geospatial data and where the
|
|
13
|
+
current tooling hurts. Open an issue with the `workflow` label.
|
|
14
|
+
- **Documentation and tutorials**, especially from a discipline we have not thought
|
|
15
|
+
about.
|
|
16
|
+
|
|
17
|
+
## Development setup
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
git clone https://github.com/agelamin17/geoai3d.git
|
|
21
|
+
cd geoai3d
|
|
22
|
+
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
23
|
+
pip install -e ".[dev]"
|
|
24
|
+
pre-commit install
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Run the checks locally before pushing:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
ruff check . && ruff format --check .
|
|
31
|
+
mypy
|
|
32
|
+
pytest -m "not gpu"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Code conventions
|
|
36
|
+
|
|
37
|
+
**API design.** The common case takes one to five lines. Expose a well-named
|
|
38
|
+
high-level function with sensible defaults, and always provide an escape hatch to
|
|
39
|
+
the underlying object for advanced users.
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
cloud = geoai3d.read_lidar("scan.laz")
|
|
43
|
+
labels = geoai3d.segment(cloud, model="ptv3-outdoor")
|
|
44
|
+
geoai3d.to_geopackage(labels, "trees.gpkg")
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Naming.** Modules are lowercase, singular, and domain-named (`lidar`, `sfm`,
|
|
48
|
+
`splat`, `annotate`, `viz`). Readers and writers are `read_*` and `to_*`, not
|
|
49
|
+
`load_*` and `save_*`. Booleans are affirmative: `include_ground`, not
|
|
50
|
+
`skip_ground`. Public names are never abbreviated: `point_cloud`, not `pc`.
|
|
51
|
+
|
|
52
|
+
**Docstrings.** Google style, on every public function: one-line summary, Args,
|
|
53
|
+
Returns, Raises, and a runnable Example. Examples must use data the package can
|
|
54
|
+
fetch automatically, so they are copy-pasteable.
|
|
55
|
+
|
|
56
|
+
**Type hints** on everything public. `mypy --strict` must pass.
|
|
57
|
+
|
|
58
|
+
**Georeferencing.** Any function returning spatial data returns it with a CRS
|
|
59
|
+
attached. If an input lacks one, raise an error naming the parameter that would fix
|
|
60
|
+
it. Never assume a default CRS, and never silently mix ellipsoidal and orthometric
|
|
61
|
+
heights.
|
|
62
|
+
|
|
63
|
+
**Devices.** Auto-detect with `device: str | None = None`. Never hard-code `.cuda()`.
|
|
64
|
+
|
|
65
|
+
**Errors.** Specific exceptions with actionable messages: what was wrong, what was
|
|
66
|
+
expected, how to fix it. No bare `except:`, no `assert` for validation.
|
|
67
|
+
|
|
68
|
+
## Testing
|
|
69
|
+
|
|
70
|
+
pytest. Every public function gets a test. Fixture point clouds live in the repo,
|
|
71
|
+
under 1 MB each. Unit tests never touch the network. Mark GPU-dependent tests with
|
|
72
|
+
`@pytest.mark.gpu` and slow ones with `@pytest.mark.slow` so CI can select.
|
|
73
|
+
|
|
74
|
+
## Dependencies
|
|
75
|
+
|
|
76
|
+
The base install must succeed on a CPU-only machine with no compiler — CI enforces
|
|
77
|
+
this in a bare container. Anything requiring CUDA, a build toolchain, or a
|
|
78
|
+
platform-specific binary goes in an optional extra. Adding a base dependency needs
|
|
79
|
+
justification in the pull request.
|
|
80
|
+
|
|
81
|
+
## Licensing
|
|
82
|
+
|
|
83
|
+
This is the one area where a mistake is expensive and hard to undo.
|
|
84
|
+
|
|
85
|
+
GEOAI_3D is MIT. Contributions must be compatible with that.
|
|
86
|
+
|
|
87
|
+
- **Do not contribute code you do not have the right to relicense**, including code
|
|
88
|
+
from paid courses or commercial training material. Capabilities may be
|
|
89
|
+
reimplemented from published literature; source may not be copied. If you learned
|
|
90
|
+
a technique from a proprietary course, implement it from the underlying paper and
|
|
91
|
+
cite the paper.
|
|
92
|
+
- **Copyleft dependencies are not acceptable in the core.** The known trap:
|
|
93
|
+
OpenDroneMap's fork of OpenSfM is AGPLv3 and incompatible with an MIT core. Use
|
|
94
|
+
Mapillary's BSD-licensed OpenSfM or COLMAP instead.
|
|
95
|
+
- **Verify model weights separately from model code.** A permissively licensed
|
|
96
|
+
architecture may ship weights under a restrictive licence. Both need checking.
|
|
97
|
+
- **Check dataset redistribution terms** before adding a loader that downloads data.
|
|
98
|
+
|
|
99
|
+
If you are unsure, open an issue before writing the code.
|
|
100
|
+
|
|
101
|
+
## AI assistance
|
|
102
|
+
|
|
103
|
+
Using AI tools to help write contributions is fine. Disclose it in the pull request
|
|
104
|
+
description — which tools, and for what. You remain responsible for correctness,
|
|
105
|
+
originality, and licensing of anything you submit. See [AI_USAGE.md](AI_USAGE.md).
|
|
106
|
+
|
|
107
|
+
## Pull requests
|
|
108
|
+
|
|
109
|
+
Keep them focused. Reference an issue where one exists. Update the CHANGELOG under
|
|
110
|
+
`Unreleased`. CI must be green.
|
|
111
|
+
|
|
112
|
+
## Code of conduct
|
|
113
|
+
|
|
114
|
+
Participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
geoai3d-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ahmed Elamin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
geoai3d-0.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: geoai3d
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Geospatial-first AI workflows for 3D data: Lidar point clouds, photogrammetry, and Gaussian splatting.
|
|
5
|
+
Project-URL: Homepage, https://github.com/agelamin17/geoai3d
|
|
6
|
+
Project-URL: Documentation, https://agelamin17.github.io/geoai3d/
|
|
7
|
+
Project-URL: Repository, https://github.com/agelamin17/geoai3d
|
|
8
|
+
Project-URL: Issues, https://github.com/agelamin17/geoai3d/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/agelamin17/geoai3d/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Ahmed Elamin <agelamin@outlook.com>
|
|
11
|
+
Maintainer-email: Ahmed Elamin <agelamin@outlook.com>
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: deep-learning,gaussian-splatting,geomatics,geospatial,gis,lidar,photogrammetry,point-cloud,remote-sensing
|
|
15
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: mypy==2.3.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: pre-commit>=3.8; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: ruff==0.15.22; extra == 'dev'
|
|
33
|
+
Provides-Extra: docs
|
|
34
|
+
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
|
|
35
|
+
Requires-Dist: mkdocs>=1.6; extra == 'docs'
|
|
36
|
+
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
|
|
37
|
+
Description-Content-Type: text/markdown
|
|
38
|
+
|
|
39
|
+
# GEOAI_3D
|
|
40
|
+
|
|
41
|
+
[](https://github.com/agelamin17/geoai3d/actions/workflows/ci.yml)
|
|
42
|
+
[](LICENSE)
|
|
43
|
+
[](https://www.python.org/)
|
|
44
|
+
|
|
45
|
+
**Geospatial-first AI workflows for 3D data.** Lidar point clouds, photogrammetry,
|
|
46
|
+
and Gaussian splatting, with coordinate reference systems, vertical datums, and
|
|
47
|
+
accuracy reporting treated as first-class concerns rather than afterthoughts.
|
|
48
|
+
|
|
49
|
+
> **Status: pre-alpha.** Version 0.0.1 is a project skeleton. It installs and does
|
|
50
|
+
> nothing. Development is happening in the open from the first commit — see the
|
|
51
|
+
> roadmap below for what lands when, and [CONTRIBUTING.md](CONTRIBUTING.md) if you
|
|
52
|
+
> want to be involved early.
|
|
53
|
+
|
|
54
|
+
## Why this exists
|
|
55
|
+
|
|
56
|
+
Working with 3D geospatial data today means assembling a pipeline by hand from
|
|
57
|
+
low-level libraries — PDAL or laspy for IO, Open3D for structures, COLMAP for
|
|
58
|
+
Structure-from-Motion, gsplat for splatting — each excellent, none aware of the
|
|
59
|
+
others, and none aware that your data has a coordinate system.
|
|
60
|
+
|
|
61
|
+
Three problems recur, and none of them are solved by any existing package:
|
|
62
|
+
|
|
63
|
+
**Scale.** A 200-million-point survey does not fit in memory. Chunked processing is
|
|
64
|
+
straightforward until you need a geometric feature computed near a tile boundary to
|
|
65
|
+
match the value it would have had on the unchunked cloud. GEOAI_3D treats that
|
|
66
|
+
seam contract as a tested guarantee, not an implementation detail.
|
|
67
|
+
|
|
68
|
+
**Vertical datums.** Most 3D tooling reduces "CRS handling" to horizontal
|
|
69
|
+
reprojection. Mixing GNSS ellipsoidal heights with an orthometric product silently
|
|
70
|
+
introduces errors of tens of metres. GEOAI_3D refuses to guess: geoid separation is
|
|
71
|
+
handled explicitly, and data without a declared vertical datum raises rather than
|
|
72
|
+
defaults.
|
|
73
|
+
|
|
74
|
+
**Accuracy.** Geomatics is the discipline that quantifies uncertainty; most 3D AI
|
|
75
|
+
tooling treats a coordinate as a fact. Per-point uncertainty, registration
|
|
76
|
+
covariance, and propagation into derived products are intended to be properties of
|
|
77
|
+
the data, not a separate analysis.
|
|
78
|
+
|
|
79
|
+
## Design commitments
|
|
80
|
+
|
|
81
|
+
These are constraints on the project, not aspirations:
|
|
82
|
+
|
|
83
|
+
- **Base install works on a CPU-only machine with no compiler.** Anything requiring
|
|
84
|
+
CUDA or a build toolchain lives in an optional extra, and CI verifies the bare
|
|
85
|
+
install in a bare container.
|
|
86
|
+
- **Cross-platform.** Linux, macOS, and Windows are tested on every commit, across
|
|
87
|
+
Python 3.10 to 3.13. Colab-friendly throughout.
|
|
88
|
+
- **Spatial reference is never optional.** Any function returning spatial data
|
|
89
|
+
returns it with a CRS attached. Missing georeferencing is an error naming the
|
|
90
|
+
parameter that would fix it, never a silent default.
|
|
91
|
+
- **Build on the ecosystem, own the middle.** PDAL, laspy, Open3D, COLMAP, and
|
|
92
|
+
gsplat are dependencies, not things to reimplement. What GEOAI_3D provides is the
|
|
93
|
+
out-of-core execution model, the datum and CRS layer, uncertainty propagation, and
|
|
94
|
+
provenance that sit between them.
|
|
95
|
+
- **Everything is provenanced.** Outputs record what produced them, from which
|
|
96
|
+
input, with which parameters and versions.
|
|
97
|
+
|
|
98
|
+
## Installation
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
pip install geoai3d
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Not yet published. Until the first release, install from source:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
git clone https://github.com/agelamin17/geoai3d.git
|
|
108
|
+
cd geoai3d
|
|
109
|
+
pip install -e ".[dev]"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Roadmap
|
|
113
|
+
|
|
114
|
+
Development is staged. Each stage ships something installable and useful on its own.
|
|
115
|
+
|
|
116
|
+
| Stage | Focus | Deliverable |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| 0 | Project skeleton, CI, open development from day one | `v0.0.1` *(current)* |
|
|
119
|
+
| 1 | Out-of-core IO, spatial indexing, CRS and vertical datums, multi-scale geometric features, provenance | `v0.1.0` on PyPI |
|
|
120
|
+
| 2 | Frugal segmentation, classical classification, GIS vector export | `v0.3.0` on PyPI and conda-forge |
|
|
121
|
+
| 3 | QGIS plugin, tutorial notebooks, tree segmentation, change detection | Plugin in the QGIS repository |
|
|
122
|
+
| 4 | Consolidation and documentation | Peer-reviewed software paper |
|
|
123
|
+
| 5 | Supervised segmentation and detection, pretrained geospatial models | `v1.0.0` and model zoo |
|
|
124
|
+
| 6 | Metric georeferenced Gaussian splatting validated against survey control | Methods paper |
|
|
125
|
+
| 7 | Annotation and labelling workflows | To be determined |
|
|
126
|
+
|
|
127
|
+
## Non-goals
|
|
128
|
+
|
|
129
|
+
Stating these early, because scope creep is the main risk to a project like this:
|
|
130
|
+
|
|
131
|
+
- Not competing with gsplat on rasterisation performance. GEOAI_3D wraps it and adds
|
|
132
|
+
georeferencing.
|
|
133
|
+
- Not a desktop GUI application. Reach for non-coders comes via the QGIS plugin.
|
|
134
|
+
- Not an autonomous-driving toolkit. Aerial, terrestrial, and survey geometry are the
|
|
135
|
+
target; automotive benchmarks and detectors are explicitly out of scope.
|
|
136
|
+
- Not a hosted service.
|
|
137
|
+
|
|
138
|
+
## Contributing
|
|
139
|
+
|
|
140
|
+
Early contributors are genuinely welcome, particularly anyone with survey control
|
|
141
|
+
data, benchmark scenes, or a workflow they would like to see supported. See
|
|
142
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) and [SUPPORT.md](SUPPORT.md).
|
|
143
|
+
|
|
144
|
+
## Citing
|
|
145
|
+
|
|
146
|
+
A software paper is planned. Until then, cite the repository via
|
|
147
|
+
[CITATION.cff](CITATION.cff).
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
MIT. See [LICENSE](LICENSE).
|
|
152
|
+
|
|
153
|
+
Code from proprietary or copyleft-incompatible sources is not accepted. See
|
|
154
|
+
[CONTRIBUTING.md](CONTRIBUTING.md#licensing) for the specific traps.
|
geoai3d-0.0.1/README.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# GEOAI_3D
|
|
2
|
+
|
|
3
|
+
[](https://github.com/agelamin17/geoai3d/actions/workflows/ci.yml)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://www.python.org/)
|
|
6
|
+
|
|
7
|
+
**Geospatial-first AI workflows for 3D data.** Lidar point clouds, photogrammetry,
|
|
8
|
+
and Gaussian splatting, with coordinate reference systems, vertical datums, and
|
|
9
|
+
accuracy reporting treated as first-class concerns rather than afterthoughts.
|
|
10
|
+
|
|
11
|
+
> **Status: pre-alpha.** Version 0.0.1 is a project skeleton. It installs and does
|
|
12
|
+
> nothing. Development is happening in the open from the first commit — see the
|
|
13
|
+
> roadmap below for what lands when, and [CONTRIBUTING.md](CONTRIBUTING.md) if you
|
|
14
|
+
> want to be involved early.
|
|
15
|
+
|
|
16
|
+
## Why this exists
|
|
17
|
+
|
|
18
|
+
Working with 3D geospatial data today means assembling a pipeline by hand from
|
|
19
|
+
low-level libraries — PDAL or laspy for IO, Open3D for structures, COLMAP for
|
|
20
|
+
Structure-from-Motion, gsplat for splatting — each excellent, none aware of the
|
|
21
|
+
others, and none aware that your data has a coordinate system.
|
|
22
|
+
|
|
23
|
+
Three problems recur, and none of them are solved by any existing package:
|
|
24
|
+
|
|
25
|
+
**Scale.** A 200-million-point survey does not fit in memory. Chunked processing is
|
|
26
|
+
straightforward until you need a geometric feature computed near a tile boundary to
|
|
27
|
+
match the value it would have had on the unchunked cloud. GEOAI_3D treats that
|
|
28
|
+
seam contract as a tested guarantee, not an implementation detail.
|
|
29
|
+
|
|
30
|
+
**Vertical datums.** Most 3D tooling reduces "CRS handling" to horizontal
|
|
31
|
+
reprojection. Mixing GNSS ellipsoidal heights with an orthometric product silently
|
|
32
|
+
introduces errors of tens of metres. GEOAI_3D refuses to guess: geoid separation is
|
|
33
|
+
handled explicitly, and data without a declared vertical datum raises rather than
|
|
34
|
+
defaults.
|
|
35
|
+
|
|
36
|
+
**Accuracy.** Geomatics is the discipline that quantifies uncertainty; most 3D AI
|
|
37
|
+
tooling treats a coordinate as a fact. Per-point uncertainty, registration
|
|
38
|
+
covariance, and propagation into derived products are intended to be properties of
|
|
39
|
+
the data, not a separate analysis.
|
|
40
|
+
|
|
41
|
+
## Design commitments
|
|
42
|
+
|
|
43
|
+
These are constraints on the project, not aspirations:
|
|
44
|
+
|
|
45
|
+
- **Base install works on a CPU-only machine with no compiler.** Anything requiring
|
|
46
|
+
CUDA or a build toolchain lives in an optional extra, and CI verifies the bare
|
|
47
|
+
install in a bare container.
|
|
48
|
+
- **Cross-platform.** Linux, macOS, and Windows are tested on every commit, across
|
|
49
|
+
Python 3.10 to 3.13. Colab-friendly throughout.
|
|
50
|
+
- **Spatial reference is never optional.** Any function returning spatial data
|
|
51
|
+
returns it with a CRS attached. Missing georeferencing is an error naming the
|
|
52
|
+
parameter that would fix it, never a silent default.
|
|
53
|
+
- **Build on the ecosystem, own the middle.** PDAL, laspy, Open3D, COLMAP, and
|
|
54
|
+
gsplat are dependencies, not things to reimplement. What GEOAI_3D provides is the
|
|
55
|
+
out-of-core execution model, the datum and CRS layer, uncertainty propagation, and
|
|
56
|
+
provenance that sit between them.
|
|
57
|
+
- **Everything is provenanced.** Outputs record what produced them, from which
|
|
58
|
+
input, with which parameters and versions.
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install geoai3d
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Not yet published. Until the first release, install from source:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
git clone https://github.com/agelamin17/geoai3d.git
|
|
70
|
+
cd geoai3d
|
|
71
|
+
pip install -e ".[dev]"
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Roadmap
|
|
75
|
+
|
|
76
|
+
Development is staged. Each stage ships something installable and useful on its own.
|
|
77
|
+
|
|
78
|
+
| Stage | Focus | Deliverable |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| 0 | Project skeleton, CI, open development from day one | `v0.0.1` *(current)* |
|
|
81
|
+
| 1 | Out-of-core IO, spatial indexing, CRS and vertical datums, multi-scale geometric features, provenance | `v0.1.0` on PyPI |
|
|
82
|
+
| 2 | Frugal segmentation, classical classification, GIS vector export | `v0.3.0` on PyPI and conda-forge |
|
|
83
|
+
| 3 | QGIS plugin, tutorial notebooks, tree segmentation, change detection | Plugin in the QGIS repository |
|
|
84
|
+
| 4 | Consolidation and documentation | Peer-reviewed software paper |
|
|
85
|
+
| 5 | Supervised segmentation and detection, pretrained geospatial models | `v1.0.0` and model zoo |
|
|
86
|
+
| 6 | Metric georeferenced Gaussian splatting validated against survey control | Methods paper |
|
|
87
|
+
| 7 | Annotation and labelling workflows | To be determined |
|
|
88
|
+
|
|
89
|
+
## Non-goals
|
|
90
|
+
|
|
91
|
+
Stating these early, because scope creep is the main risk to a project like this:
|
|
92
|
+
|
|
93
|
+
- Not competing with gsplat on rasterisation performance. GEOAI_3D wraps it and adds
|
|
94
|
+
georeferencing.
|
|
95
|
+
- Not a desktop GUI application. Reach for non-coders comes via the QGIS plugin.
|
|
96
|
+
- Not an autonomous-driving toolkit. Aerial, terrestrial, and survey geometry are the
|
|
97
|
+
target; automotive benchmarks and detectors are explicitly out of scope.
|
|
98
|
+
- Not a hosted service.
|
|
99
|
+
|
|
100
|
+
## Contributing
|
|
101
|
+
|
|
102
|
+
Early contributors are genuinely welcome, particularly anyone with survey control
|
|
103
|
+
data, benchmark scenes, or a workflow they would like to see supported. See
|
|
104
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) and [SUPPORT.md](SUPPORT.md).
|
|
105
|
+
|
|
106
|
+
## Citing
|
|
107
|
+
|
|
108
|
+
A software paper is planned. Until then, cite the repository via
|
|
109
|
+
[CITATION.cff](CITATION.cff).
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
MIT. See [LICENSE](LICENSE).
|
|
114
|
+
|
|
115
|
+
Code from proprietary or copyleft-incompatible sources is not accepted. See
|
|
116
|
+
[CONTRIBUTING.md](CONTRIBUTING.md#licensing) for the specific traps.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
The project is pre-alpha. Only the latest release receives fixes.
|
|
6
|
+
|
|
7
|
+
## Reporting a vulnerability
|
|
8
|
+
|
|
9
|
+
Report privately via GitHub's [security advisory
|
|
10
|
+
form](https://github.com/agelamin17/geoai3d/security/advisories/new), or by email
|
|
11
|
+
to agelamin@outlook.com. Please do not open a public issue.
|
|
12
|
+
|
|
13
|
+
Expect an acknowledgement within one week. Because this is a part-time project,
|
|
14
|
+
please allow a reasonable window for a fix before public disclosure.
|
|
15
|
+
|
|
16
|
+
## Scope note
|
|
17
|
+
|
|
18
|
+
GEOAI_3D parses binary geospatial formats and, in later stages, loads model
|
|
19
|
+
weights. Malformed files and untrusted checkpoints are realistic attack surfaces;
|
|
20
|
+
reports in these areas are particularly welcome.
|
geoai3d-0.0.1/SUPPORT.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Support
|
|
2
|
+
|
|
3
|
+
## What to expect
|
|
4
|
+
|
|
5
|
+
GEOAI_3D is maintained by a single researcher working on it part-time. Being
|
|
6
|
+
explicit about that, so expectations are calibrated:
|
|
7
|
+
|
|
8
|
+
- **Bug reports:** triaged within roughly two weeks. Reproducible reports with a
|
|
9
|
+
minimal example get looked at first.
|
|
10
|
+
- **Feature requests:** read, labelled, and mapped onto the roadmap. Many will be
|
|
11
|
+
deferred to a later stage rather than declined — the roadmap in the README shows
|
|
12
|
+
the ordering and the reasoning.
|
|
13
|
+
- **Questions:** use GitHub Discussions rather than the issue tracker.
|
|
14
|
+
- **Security issues:** see [SECURITY.md](SECURITY.md). Do not open a public issue.
|
|
15
|
+
|
|
16
|
+
There is no commercial support offering and no service-level agreement.
|
|
17
|
+
|
|
18
|
+
## Getting help effectively
|
|
19
|
+
|
|
20
|
+
Include your operating system, Python version, `geoai3d` version, how you installed
|
|
21
|
+
it, the full traceback, and — if the problem involves data — the CRS and
|
|
22
|
+
approximate point count. A small file that reproduces the issue is worth more than
|
|
23
|
+
a long description.
|
|
24
|
+
|
|
25
|
+
## Governance
|
|
26
|
+
|
|
27
|
+
Decisions currently rest with the maintainer. As contributors accumulate this will
|
|
28
|
+
be replaced by something more formal; the project actively wants to reach that
|
|
29
|
+
point, and anyone interested in co-maintaining should open an issue.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Contributing to GEOAI_3D
|
|
2
|
+
|
|
3
|
+
Contributions are welcome at any scale, from a typo fix to a new module. This
|
|
4
|
+
document covers how to work on the code and the few rules that are not negotiable.
|
|
5
|
+
|
|
6
|
+
## Ways to help that are not code
|
|
7
|
+
|
|
8
|
+
The project needs these at least as much as it needs pull requests:
|
|
9
|
+
|
|
10
|
+
- **Test data.** Point clouds with known, independently surveyed control. This is
|
|
11
|
+
the scarcest resource in the project.
|
|
12
|
+
- **Workflow reports.** Tell us what you do with 3D geospatial data and where the
|
|
13
|
+
current tooling hurts. Open an issue with the `workflow` label.
|
|
14
|
+
- **Documentation and tutorials**, especially from a discipline we have not thought
|
|
15
|
+
about.
|
|
16
|
+
|
|
17
|
+
## Development setup
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
git clone https://github.com/agelamin17/geoai3d.git
|
|
21
|
+
cd geoai3d
|
|
22
|
+
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
23
|
+
pip install -e ".[dev]"
|
|
24
|
+
pre-commit install
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Run the checks locally before pushing:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
ruff check . && ruff format --check .
|
|
31
|
+
mypy
|
|
32
|
+
pytest -m "not gpu"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Code conventions
|
|
36
|
+
|
|
37
|
+
**API design.** The common case takes one to five lines. Expose a well-named
|
|
38
|
+
high-level function with sensible defaults, and always provide an escape hatch to
|
|
39
|
+
the underlying object for advanced users.
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
cloud = geoai3d.read_lidar("scan.laz")
|
|
43
|
+
labels = geoai3d.segment(cloud, model="ptv3-outdoor")
|
|
44
|
+
geoai3d.to_geopackage(labels, "trees.gpkg")
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Naming.** Modules are lowercase, singular, and domain-named (`lidar`, `sfm`,
|
|
48
|
+
`splat`, `annotate`, `viz`). Readers and writers are `read_*` and `to_*`, not
|
|
49
|
+
`load_*` and `save_*`. Booleans are affirmative: `include_ground`, not
|
|
50
|
+
`skip_ground`. Public names are never abbreviated: `point_cloud`, not `pc`.
|
|
51
|
+
|
|
52
|
+
**Docstrings.** Google style, on every public function: one-line summary, Args,
|
|
53
|
+
Returns, Raises, and a runnable Example. Examples must use data the package can
|
|
54
|
+
fetch automatically, so they are copy-pasteable.
|
|
55
|
+
|
|
56
|
+
**Type hints** on everything public. `mypy --strict` must pass.
|
|
57
|
+
|
|
58
|
+
**Georeferencing.** Any function returning spatial data returns it with a CRS
|
|
59
|
+
attached. If an input lacks one, raise an error naming the parameter that would fix
|
|
60
|
+
it. Never assume a default CRS, and never silently mix ellipsoidal and orthometric
|
|
61
|
+
heights.
|
|
62
|
+
|
|
63
|
+
**Devices.** Auto-detect with `device: str | None = None`. Never hard-code `.cuda()`.
|
|
64
|
+
|
|
65
|
+
**Errors.** Specific exceptions with actionable messages: what was wrong, what was
|
|
66
|
+
expected, how to fix it. No bare `except:`, no `assert` for validation.
|
|
67
|
+
|
|
68
|
+
## Testing
|
|
69
|
+
|
|
70
|
+
pytest. Every public function gets a test. Fixture point clouds live in the repo,
|
|
71
|
+
under 1 MB each. Unit tests never touch the network. Mark GPU-dependent tests with
|
|
72
|
+
`@pytest.mark.gpu` and slow ones with `@pytest.mark.slow` so CI can select.
|
|
73
|
+
|
|
74
|
+
## Dependencies
|
|
75
|
+
|
|
76
|
+
The base install must succeed on a CPU-only machine with no compiler — CI enforces
|
|
77
|
+
this in a bare container. Anything requiring CUDA, a build toolchain, or a
|
|
78
|
+
platform-specific binary goes in an optional extra. Adding a base dependency needs
|
|
79
|
+
justification in the pull request.
|
|
80
|
+
|
|
81
|
+
## Licensing
|
|
82
|
+
|
|
83
|
+
This is the one area where a mistake is expensive and hard to undo.
|
|
84
|
+
|
|
85
|
+
GEOAI_3D is MIT. Contributions must be compatible with that.
|
|
86
|
+
|
|
87
|
+
- **Do not contribute code you do not have the right to relicense**, including code
|
|
88
|
+
from paid courses or commercial training material. Capabilities may be
|
|
89
|
+
reimplemented from published literature; source may not be copied. If you learned
|
|
90
|
+
a technique from a proprietary course, implement it from the underlying paper and
|
|
91
|
+
cite the paper.
|
|
92
|
+
- **Copyleft dependencies are not acceptable in the core.** The known trap:
|
|
93
|
+
OpenDroneMap's fork of OpenSfM is AGPLv3 and incompatible with an MIT core. Use
|
|
94
|
+
Mapillary's BSD-licensed OpenSfM or COLMAP instead.
|
|
95
|
+
- **Verify model weights separately from model code.** A permissively licensed
|
|
96
|
+
architecture may ship weights under a restrictive licence. Both need checking.
|
|
97
|
+
- **Check dataset redistribution terms** before adding a loader that downloads data.
|
|
98
|
+
|
|
99
|
+
If you are unsure, open an issue before writing the code.
|
|
100
|
+
|
|
101
|
+
## AI assistance
|
|
102
|
+
|
|
103
|
+
Using AI tools to help write contributions is fine. Disclose it in the pull request
|
|
104
|
+
description — which tools, and for what. You remain responsible for correctness,
|
|
105
|
+
originality, and licensing of anything you submit. See [AI_USAGE.md](AI_USAGE.md).
|
|
106
|
+
|
|
107
|
+
## Pull requests
|
|
108
|
+
|
|
109
|
+
Keep them focused. Reference an issue where one exists. Update the CHANGELOG under
|
|
110
|
+
`Unreleased`. CI must be green.
|
|
111
|
+
|
|
112
|
+
## Code of conduct
|
|
113
|
+
|
|
114
|
+
Participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# GEOAI_3D
|
|
2
|
+
|
|
3
|
+
Geospatial-first AI workflows for 3D data.
|
|
4
|
+
|
|
5
|
+
!!! warning "Pre-alpha"
|
|
6
|
+
Version 0.0.1 is a project skeleton. It installs and does nothing. This
|
|
7
|
+
documentation site exists from the first commit so that it grows alongside
|
|
8
|
+
the code rather than being assembled at the end.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install geoai3d
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Not yet published. Install from source in the meantime:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
git clone https://github.com/agelamin17/geoai3d.git
|
|
20
|
+
cd geoai3d
|
|
21
|
+
pip install -e ".[dev]"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## What is planned
|
|
25
|
+
|
|
26
|
+
Stage 1 delivers the foundation: out-of-core reading and processing of Lidar point
|
|
27
|
+
clouds beyond available memory, spatial indexing, explicit handling of horizontal
|
|
28
|
+
and vertical coordinate reference systems, multi-scale geometric feature
|
|
29
|
+
computation with a tested tile-seam guarantee, and provenance recording on every
|
|
30
|
+
output.
|
|
31
|
+
|
|
32
|
+
Later stages add unsupervised geometric segmentation, GIS vector export, a QGIS
|
|
33
|
+
plugin, supervised semantic segmentation with pretrained models for geospatial
|
|
34
|
+
classes, and metric georeferenced Gaussian splatting.
|
|
35
|
+
|
|
36
|
+
See the [roadmap in the README](https://github.com/agelamin17/geoai3d#roadmap).
|
|
37
|
+
|
|
38
|
+
## Getting involved
|
|
39
|
+
|
|
40
|
+
The project is developed in the open and welcomes early involvement, particularly
|
|
41
|
+
from anyone holding point cloud data with independently surveyed control.
|
geoai3d-0.0.1/mkdocs.yml
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
site_name: GEOAI_3D
|
|
2
|
+
site_description: Geospatial-first AI workflows for 3D data
|
|
3
|
+
repo_url: https://github.com/agelamin17/geoai3d
|
|
4
|
+
repo_name: agelamin17/geoai3d
|
|
5
|
+
edit_uri: edit/main/docs/
|
|
6
|
+
|
|
7
|
+
theme:
|
|
8
|
+
name: material
|
|
9
|
+
features:
|
|
10
|
+
- navigation.sections
|
|
11
|
+
- content.code.copy
|
|
12
|
+
- content.action.edit
|
|
13
|
+
palette:
|
|
14
|
+
- media: "(prefers-color-scheme: light)"
|
|
15
|
+
scheme: default
|
|
16
|
+
toggle:
|
|
17
|
+
icon: material/weather-night
|
|
18
|
+
name: Switch to dark mode
|
|
19
|
+
- media: "(prefers-color-scheme: dark)"
|
|
20
|
+
scheme: slate
|
|
21
|
+
toggle:
|
|
22
|
+
icon: material/weather-sunny
|
|
23
|
+
name: Switch to light mode
|
|
24
|
+
|
|
25
|
+
plugins:
|
|
26
|
+
- search
|
|
27
|
+
- mkdocstrings:
|
|
28
|
+
handlers:
|
|
29
|
+
python:
|
|
30
|
+
options:
|
|
31
|
+
docstring_style: google
|
|
32
|
+
show_source: true
|
|
33
|
+
|
|
34
|
+
markdown_extensions:
|
|
35
|
+
- admonition
|
|
36
|
+
- pymdownx.details
|
|
37
|
+
- pymdownx.superfences
|
|
38
|
+
- toc:
|
|
39
|
+
permalink: true
|
|
40
|
+
|
|
41
|
+
nav:
|
|
42
|
+
- Home: index.md
|
|
43
|
+
- Contributing: contributing.md
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "geoai3d"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Geospatial-first AI workflows for 3D data: Lidar point clouds, photogrammetry, and Gaussian splatting."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [{ name = "Ahmed Elamin", email = "agelamin@outlook.com" }]
|
|
14
|
+
maintainers = [{ name = "Ahmed Elamin", email = "agelamin@outlook.com" }]
|
|
15
|
+
keywords = [
|
|
16
|
+
"lidar", "point-cloud", "geospatial", "gis", "remote-sensing",
|
|
17
|
+
"photogrammetry", "gaussian-splatting", "deep-learning", "geomatics",
|
|
18
|
+
]
|
|
19
|
+
classifiers = [
|
|
20
|
+
"Development Status :: 2 - Pre-Alpha",
|
|
21
|
+
"Intended Audience :: Science/Research",
|
|
22
|
+
"Operating System :: OS Independent",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Topic :: Scientific/Engineering :: GIS",
|
|
29
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
30
|
+
"Typing :: Typed",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
# Base install must succeed on a CPU-only machine with no compiler.
|
|
34
|
+
# Anything needing CUDA or a build toolchain belongs in an optional extra.
|
|
35
|
+
dependencies = []
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
dev = [
|
|
39
|
+
"pytest>=8.0",
|
|
40
|
+
"pytest-cov>=5.0",
|
|
41
|
+
"ruff==0.15.22",
|
|
42
|
+
"mypy==2.3.0",
|
|
43
|
+
"pre-commit>=3.8",
|
|
44
|
+
]
|
|
45
|
+
docs = [
|
|
46
|
+
"mkdocs>=1.6",
|
|
47
|
+
"mkdocs-material>=9.5",
|
|
48
|
+
"mkdocstrings[python]>=0.26",
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
[project.urls]
|
|
52
|
+
Homepage = "https://github.com/agelamin17/geoai3d"
|
|
53
|
+
Documentation = "https://agelamin17.github.io/geoai3d/"
|
|
54
|
+
Repository = "https://github.com/agelamin17/geoai3d"
|
|
55
|
+
Issues = "https://github.com/agelamin17/geoai3d/issues"
|
|
56
|
+
Changelog = "https://github.com/agelamin17/geoai3d/blob/main/CHANGELOG.md"
|
|
57
|
+
|
|
58
|
+
[tool.hatch.version]
|
|
59
|
+
path = "src/geoai3d/__init__.py"
|
|
60
|
+
|
|
61
|
+
[tool.hatch.build.targets.wheel]
|
|
62
|
+
packages = ["src/geoai3d"]
|
|
63
|
+
|
|
64
|
+
[tool.pytest.ini_options]
|
|
65
|
+
minversion = "8.0"
|
|
66
|
+
testpaths = ["tests"]
|
|
67
|
+
addopts = "-ra --strict-markers --strict-config"
|
|
68
|
+
markers = [
|
|
69
|
+
"gpu: requires a CUDA-capable GPU (deselect with '-m \"not gpu\"')",
|
|
70
|
+
"slow: takes more than a few seconds",
|
|
71
|
+
"network: requires network access (never used in unit tests)",
|
|
72
|
+
]
|
|
73
|
+
|
|
74
|
+
[tool.ruff]
|
|
75
|
+
line-length = 88
|
|
76
|
+
target-version = "py310"
|
|
77
|
+
src = ["src", "tests"]
|
|
78
|
+
|
|
79
|
+
[tool.ruff.lint]
|
|
80
|
+
select = [
|
|
81
|
+
"E", "W", # pycodestyle
|
|
82
|
+
"F", # pyflakes
|
|
83
|
+
"I", # isort
|
|
84
|
+
"N", # pep8-naming
|
|
85
|
+
"UP", # pyupgrade
|
|
86
|
+
"B", # flake8-bugbear
|
|
87
|
+
"A", # flake8-builtins
|
|
88
|
+
"C4", # flake8-comprehensions
|
|
89
|
+
"PT", # flake8-pytest-style
|
|
90
|
+
"SIM", # flake8-simplify
|
|
91
|
+
"RUF", # ruff-specific
|
|
92
|
+
"D", # pydocstyle
|
|
93
|
+
"ANN", # flake8-annotations
|
|
94
|
+
]
|
|
95
|
+
ignore = ["D203", "D213", "ANN401"]
|
|
96
|
+
|
|
97
|
+
[tool.ruff.lint.pydocstyle]
|
|
98
|
+
convention = "google"
|
|
99
|
+
|
|
100
|
+
[tool.ruff.lint.per-file-ignores]
|
|
101
|
+
"tests/*" = ["D103", "ANN201"]
|
|
102
|
+
|
|
103
|
+
[tool.mypy]
|
|
104
|
+
python_version = "3.10"
|
|
105
|
+
strict = true
|
|
106
|
+
warn_unreachable = true
|
|
107
|
+
files = ["src", "tests"]
|
|
108
|
+
|
|
109
|
+
[tool.coverage.run]
|
|
110
|
+
source = ["src/geoai3d"]
|
|
111
|
+
branch = true
|
|
112
|
+
|
|
113
|
+
[tool.coverage.report]
|
|
114
|
+
show_missing = true
|
|
File without changes
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""Smoke tests for the package skeleton.
|
|
2
|
+
|
|
3
|
+
These exist so that continuous integration has something real to run from the
|
|
4
|
+
first commit onward. They are replaced by feature tests as modules land.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import re
|
|
8
|
+
|
|
9
|
+
import geoai3d
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def test_package_imports() -> None:
|
|
13
|
+
"""The package imports cleanly on a bare interpreter."""
|
|
14
|
+
assert geoai3d is not None
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def test_version_is_pep440_compatible() -> None:
|
|
18
|
+
"""__version__ is present and parseable as a simple release version."""
|
|
19
|
+
pattern = r"\d+\.\d+\.\d+(?:[.-]?(?:a|b|rc|dev)\d+)?"
|
|
20
|
+
assert re.fullmatch(pattern, geoai3d.__version__)
|