KẾ HOẠCH PHÁT TRIỂN

TopoFix

Lộ trình nghiên cứu, học tập & xây dựng công cụ GIS thế hệ mới

Lộc Vũ Trung tổng hợp từ đam mê

Phiên bản 2.0 — Tháng 5/2026

Chiến lược Hi-Tech • Kiến trúc Module • AI-Ready

# PHẦN I — NỀN TẢNG LÝ THUYẾT GIS

## 1.1 OGC Simple Feature (ISO 19125)

Tiêu chuẩn quốc tế định nghĩa quan hệ topology — nền tảng cho mọi công cụ GIS hiện đại.

Quan hệ | Định nghĩa | Ứng dụng
--- | --- | ---
Equals | A và B đồng nhất geometry | Phát hiện trùng lặp
Disjoint | Không có điểm chung | Đảo của Intersects
Intersects | Có ≥1 điểm chung | Lọc ứng viên overlap
Touches | Chỉ chung boundary | Phát hiện Gaps
Overlaps | Giao nhau, không chứa nhau | Phát hiện chồng đè
Contains | A chứa B hoàn toàn | Kiểm tra ràng buộc spatial

### Ma trận DE-9IM

Dimensionally Extended 9-Intersection Model — mô tả chính xác mọi quan hệ không gian:

Overlaps: T*T***T** | Contains: T*****FF* | Touches: FT*******

💡 MẸO THỰC HÀNH

Trong QGIS Python: g1.relate(g2) trả về chuỗi DE-9IM 9 ký tự. Dùng để debug quan hệ spatial phức tạp.

## 1.2 GEOS — Engine tính toán hình học

Thư viện C++ nền tảng của PostGIS, QGIS, Shapely:

GEOS Function | QGIS Python API | Mục đích
--- | --- | ---
GEOSisValid() | QgsGeometry.isGeosValid() | Kiểm tra hợp lệ
GEOSOverlaps() | g.overlaps(other) | Phát hiện chồng đè
GEOSIntersection() | g.intersection(other) | Tính phần giao
GEOSDifference() | g.difference(other) | Tính phần hiệu
GEOSBuffer() | g.buffer(distance) | Vùng đệm / làm sạch
GEOSUnaryUnion() | QgsGeometry.unaryUnion() | Dissolve geometry
GEOSMakeValid() | g.makeValid() | Sửa geometry

## 1.3 Computational Geometry

### Point-on-Segment Test

Thuật toán cốt lõi phát hiện nút thiếu trên cạnh chung:

t = dot(AP, AB) / dot(AB, AB)

F = A + t × AB

P ∈ AB ⟺ 0 < t < 1 AND |PF| < tolerance

### Douglas-Peucker Algorithm

Giảm số đỉnh polyline/polygon mà bảo toàn hình dạng:

### R-Tree Spatial Indexing

Giảm O(n²) → O(n·log n) bằng phân cấp không gian:

⚡ HIỆU SUẤT

QgsSpatialIndex là wrapper Python cho R-Tree. Tiết kiệm 90%+ thời gian trên dataset lớn.

## 1.4 Geometry Validity (OGC)

- Rings khép kín: Điểm đầu ≡ điểm cuối
- Không tự cắt: Boundary không intersect chính nó
- Holes nằm trong shell
- Holes không giao nhau
- Hướng: Exterior = CCW, Interior = CW
- Đủ điểm: ≥ 4 vertices

Phương pháp | Mô tả | Khi nào dùng
--- | --- | ---
makeValid() | GEOS MakeValid | Default, an toàn
buffer(0) | Buffer zero clean | Nhanh, có thể mất detail
fixGeometries (Structure) | QGIS Processing | Dữ liệu ranh giới
fixGeometries (Linework) | QGIS Processing | Dữ liệu hiện trạng

# PHẦN II — LỘ TRÌNH HỌC TẬP

🎯 CHIẾN LƯỢC HI-TECH

4 trụ cột: (1) Lý thuyết OGC/GEOS → (2) Thuật toán tự phát triển → (3) Kiến trúc module hóa → (4) CI/CD & AI-assisted. Mục tiêu: toolkit GIS thế hệ mới.

## Giai đoạn 1: Nền tảng (2 tuần)

Ngày | Nội dung | Tài liệu
--- | --- | ---
1-2 | OGC Simple Feature, DE-9IM | ISO 19125-1
3-4 | GEOS: validity, spatial predicates | libgeos.org
5-6 | Spatial indexing: R-Tree | 'Computational Geometry' — de Berg
7-8 | QGIS Python API | PyQGIS Cookbook
9-10 | PyQt: QDialog, QThread, signals/slots | Qt 6 docs
11-12 | QGIS Processing Framework | QGIS docs
13-14 | Thực hành: script geometry validity | Dữ liệu VN-2000

## Giai đoạn 2: Thuật toán Core (3 tuần)

Tuần | Thuật toán | Độ khó | Kỹ thuật
--- | --- | --- | ---
1 | Duplicates | ★☆☆ | WKT hash O(n)
1 | Invalid Geometries | ★☆☆ | isGeosValid()
1 | Multipart / Unclosed | ★☆☆ | API check
2 | Redundant Vertices | ★☆☆ | Douglas-Peucker
2 | Sliver / Tiny Polygons | ★★☆ | Compactness P/√A
2 | Overlaps | ★★☆ | R-Tree + intersection()
3 | Gaps | ★★★ | Dissolve + hole extraction
3 | Must Not Overlap | ★★★ | Area-based difference()
3 | Missing Nodes | ★★★★ | Custom projection + rebuild

## Giai đoạn 3: Thuật toán Fix (3 tuần)

Tuần | Fix | Phương pháp
--- | --- | ---
1 | Invalid + Unclosed + Multipart | native:fixgeometries + multiparttosingleparts
1 | Duplicate + Redundant | deleteduplicategeometries + simplifygeometries
2 | Overlap + Must Not Overlap | Custom: SpatialIndex → intersection → difference
2 | Sliver | Filter by compactness ratio
3 | Gap + Missing Nodes | Dissolve merge + custom vertex insertion
3 | Tiny Polygon | Iterative merge (max 20 rounds)

## Giai đoạn 4: Tích hợp (2 tuần)

Tuần | Nội dung
--- | ---
1 | UI (QDialog + QSS themes), Threading (QThread + pyqtSignal), Progress + Cancel
2 | Plugin packaging, metadata.txt, unit tests, CI pipeline

# PHẦN III — CHIẾN LƯỢC HI-TECH

## 3.1 Kiến trúc Module

topofix/

├── __init__.py # Plugin entry

├── ui/ # Presentation Layer

│ ├── main_dialog.py # QDialog responsive

│ └── themes.py # Dark/Light QSS

├── core/ # Business Logic

│ ├── checker.py / fixer.py # QThread workers

│ └── pipeline.py # Fix orchestrator

├── algorithms/ # Pluggable modules

│ ├── base.py # Abstract interface

│ ├── [10 modules].py # check() + fix()

│ └── registry.py # Auto-discover

├── utils/ # Shared utilities

└── tests/ # Automated testing

## 3.2 Nguyên tắc thiết kế

1. Plugin Architecture: Mỗi algorithm là module độc lập, đăng ký qua registry — thêm/bớt không sửa core.

2. Interface chuẩn: Mọi module implement check(layer, params) và fix(layer, output, params).

3. Multi-format: Shapefile + GeoPackage + GeoJSON — không lock format.

4. Cross-platform: Windows, Linux, macOS — không OS-specific API.

5. Open-source: Python rõ ràng, có docstring, dễ maintain.

🔮 TẦM NHÌN AI-READY

Kiến trúc module cho phép tích hợp ML: auto-detect parameters, predict error zones, smart merge decisions từ attributes.

## 3.3 Công nghệ hiện đại

Lĩnh vực | Công cụ | Lợi ích
--- | --- | ---
Version Control | Git + GitHub Actions CI/CD | Tự động test mỗi commit
Testing | pytest + QgsTestCase | Unit test từng algorithm
Code Quality | mypy + ruff + pre-commit | Type safety + clean code
Documentation | Sphinx + autodoc | API docs tự sinh
Profiling | cProfile + memory_profiler | Tối ưu bottleneck
Parallel | concurrent.futures + QThread | Multi-core batch
Logging | QgsMessageLog | Debug production

## 3.4 Năng lực hệ thống

Tính năng | Năng lực hệ thống
--- | ---
Output format | Shapefile + GeoPackage + GeoJSON + PostGIS export
Nền tảng | Cross-platform: Windows, Linux, macOS
Source code | Open-source Python rõ ràng, có docstring
Kiến trúc | Modular pluggable — thêm algorithm không sửa core
Testing | pytest suite coverage ≥ 80% cho mỗi algorithm
License | Tự do, không phụ thuộc server bên ngoài
CRS | Tự động detect + chuyển đổi đơn vị mét/độ
Batch | Multi-layer batch processing đồng thời
Logging | QGIS Log Messages + file log integration
Mở rộng | Plugin registry — đăng ký algorithm mới dễ dàng

# PHẦN IV — TÀI LIỆU THAM KHẢO

## Sách & Tiêu chuẩn

- ISO 19125 — Simple feature access
- 'Computational Geometry' — de Berg et al.
- 'GIS Algorithms' — Xiao (CRC Press)

## Documentation

- GEOS — libgeos.org/usage/
- PostGIS Topology — postgis.net/docs/Topology.html
- PyQGIS Developer Cookbook — docs.qgis.org
- Shapely — shapely.readthedocs.io
- JTS — github.com/locationtech/jts

## Khóa học

- MIT OCW 6.850 — Computational Geometry
- QGIS Plugin Development — YouTube

# PHẦN V — CHECKLIST RELEASE

☐ [Thuật toán] 11 check + 10 fix algorithms hoạt động chính xác

☐ [Pipeline] Fix tuần tự 10 bước, output N = input N+1

☐ [Testing] pytest pass 100%, coverage ≥ 80%

☐ [Dữ liệu] Test trên VN-2000 + WGS84 + UTM thực tế

☐ [UI/UX] Responsive, progress bar, dark/light theme

☐ [Threading] Cancel/Stop đúng, không memory leak

☐ [Error] Không crash với empty geometry, null CRS

☐ [Output] File mở được trong QGIS, ArcGIS Pro

☐ [Platform] Test Windows 10/11 + Ubuntu 22.04

☐ [Docs] README + API docs + user guide đầy đủ

☐ [CI/CD] GitHub Actions: lint + test + package tự động