HƯỚNG DẪN SỬ DỤNG

TopoFix

Plugin kiểm tra & sửa lỗi topology cho QGIS
18 thuật toán: 🔷 Polygon (11) | 📏 Line (4) | 📍 Point (3)

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

# 1. Cài đặt và Khởi động

## Yêu cầu hệ thống

- QGIS >= 3.0 (khuyến nghị 3.28+)
- Python 3.12 (đi kèm QGIS)
- Kết nối Internet (lần đầu cài đặt dependencies)
- Hệ điều hành: Windows / Linux / macOS

## Cài đặt plugin

- Copy thư mục 'TopoFix' vào: %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\
- Khởi động QGIS
- Vào Plugins > Manage and Install Plugins > Installed
- Tích chọn 'TopoFix'
- Icon sẽ xuất hiện trên toolbar

# 2. Giao diện chính

TopoFix sử dụng giao diện tiết lộ dần (progressive disclosure) — chỉ hiện thông tin cần thiết.

## Trạng thái 1: Khởi động

- Chỉ hiện: Chọn layer (dropdown) + nút 🔍 Scan All Errors
- Bảng lỗi và tham số ẩn hoàn toàn

## Trạng thái 2: Kết quả

Sau khi scan xong, chỉ hiện các loại lỗi có count > 0. Những loại = 0 được ẩn.

Cột | Widget | Chức năng
--- | --- | ---
Loại lỗi | QLabel | Tên lỗi, mã màu riêng
Số lượng | QLabel | Số lỗi (đỏ, đậm)
Highlight | QPushButton | Tô sáng lỗi trên bản đồ (memory layer)
Sửa | QCheckBox | Tích để sửa loại lỗi này

## Trạng thái 3: Tham số nâng cao

Panel ⚙ Advanced Parameters chỉ hiện khi có lỗi liên quan, và chỉ hiện tham số tương ứng.

Tham số | Mặc định | Ý nghĩa
--- | --- | ---
Gap tolerance | 0.001 ha | Gap nhỏ hơn bị bỏ qua
Sliver max area | 1.0 ha | Lớn hơn không phải sliver
Sliver ratio P/√A | 20.0 | Ngưỡng compactness
MNO min area | 0.001 m² | Chỉ cắt giao lớn hơn
Missing node tol | 0.001 | VN-2000: 0.001m, WGS84: 1e-8
Tiny polygon min | (tùy dữ liệu) | Nhỏ hơn thì gộp
Max vertices | 500 | Vượt quá là dư thừa

# 3. Quy trình sử dụng

## Bước 1: Chuẩn bị

- Mở project QGIS chứa layer vector cần kiểm tra (Point, Line, hoặc Polygon)
- Đảm bảo CRS đúng (VN-2000 hoặc WGS84)
- KHUYẾN NGHỊ: Backup dữ liệu trước khi sửa

## Bước 2: Scan lỗi

- Mở TopoFix từ menu LVT4U → TopoFix hoặc toolbar
- Chọn layer từ dropdown — hiện icon theo loại: 📍 Point, 📏 Line, 🔷 Polygon
- Click 🔍 Scan All Errors
- TopoFix tự động nhận diện loại geometry và áp dụng bộ thuật toán phù hợp
- Bước tiền xử lý Fix Geometries chạy ngầm trước khi scan
- Chờ progress bar hoàn thành

Tự động nhận diện: Không cần chọn loại geometry — TopoFix tự phát hiện Point/Line/Polygon và hiển thị đúng bộ thuật toán tương ứng.

## Bước 3: Xem kết quả

- Chỉ các loại lỗi có count > 0 được hiện ra
- Nếu ✅ No errors found — layer sạch!
- Click Show để tô sáng lỗi trên bản đồ (memory layer tạm)
- QGIS tự zoom đến vùng lỗi, dùng Identify tool để xem chi tiết

## Bước 4: Sửa lỗi

- Tick checkbox Fix cho các loại lỗi muốn sửa (mặc định: tất cả)
- Điều chỉnh tham số trong panel ⚙ Advanced Parameters nếu cần
- Click 🔧 Fix Errors → Xác nhận
- Layer ảo `*_TopoFixed` được tạo để review

## Bước 5: Kiểm tra lại

- Click 🔄 Re-Scan để quét lại (layer TopoFixed tự nạp vào dropdown)
- Lặp lại cho đến khi sạch lỗi
- Khi hài lòng: chuột phải layer → Export → Save Features As...

⚠ Một số lỗi có thể xuất hiện mới sau khi sửa (cascade effect).

# 4. Thứ tự ưu tiên sửa lỗi

Plugin tự động thực hiện đúng thứ tự này:

# | Loại lỗi | Hành động
--- | --- | ---
1 | Multipart | Tách trước, tăng số features
2 | Invalid | Sửa cấu trúc geometry
3 | Duplicate | Xóa bản trùng
4 | Overlap | Cắt phần chồng đè
5 | Must Not Overlap | Cắt thông minh theo diện tích
6 | Gap | Lấp khoảng hở
7 | Redundant | Giảm số đỉnh
8 | Sliver | Loại mảnh vụn
9 | Missing Node | Chèn nút thiếu
10 | Tiny Polygon | Gộp polygon nhỏ

⚠ Nên sửa TẤT CẢ cùng lúc, không sửa riêng lẻ từng loại.

# 5. Kiểm tra dữ liệu ĐƯỜNG (Line)

Khi chọn layer dạng Line, TopoFix tự động chuyển sang 4 thuật toán chuyên biệt:

# | Loại lỗi | Mô tả | Sửa tự động?
--- | --- | --- | ---
1 | 📏 Dangles | Đầu mút treo — endpoint không kết nối đường nào | ❌ Cần xem xét
2 | 📏 Self-Intersection | Đường tự cắt chính nó | ✅ Fix Geometries
3 | 📏 Duplicate Lines | Hai đường có geometry hoàn toàn giống nhau | ✅ Xóa bản trùng
4 | 📏 Overlapping Lines | Hai đường có đoạn trùng nhau | ❌ Cần xem xét

Ứng dụng: Kiểm tra mạng lưới đường giao thông, thủy văn, đường dây điện, ranh giới hành chính dạng line. Đặc biệt hữu ích cho dữ liệu số hóa thủ công.

# 6. Kiểm tra dữ liệu ĐIỂM (Point)

Khi chọn layer dạng Point, TopoFix tự động chuyển sang 3 thuật toán chuyên biệt:

# | Loại lỗi | Mô tả | Sửa tự động?
--- | --- | --- | ---
1 | 📍 Duplicate Points | Nhiều điểm trùng tọa độ (trong tolerance) | ✅ Xóa bản trùng
2 | 📍 Invalid Coordinates | Tọa độ NaN, Infinity, hoặc ngoài phạm vi | ✅ Xóa điểm lỗi
3 | 📍 Isolated Points | Điểm nằm quá xa mọi điểm khác | ❌ Cần xem xét

Ứng dụng: Kiểm tra dữ liệu GPS, khảo sát thực địa, điểm mẫu (sample points), trạm quan trắc, cây trồng, mốc ranh giới.

# 7. Lưu ý thực tế

## Dữ liệu VN-2000

- CRS: VN-2000 3-degree zone (EPSG tùy tỉnh)
- Đơn vị: mét → tham số nhập trực tiếp
- Missing node tolerance: 0.001 → 0.01 mét

## Hiệu suất

Kích thước layer | Loại | Thời gian ước tính
--- | --- | ---
< 1,000 features | Tất cả | Vài giây
1,000 – 10,000 features | Polygon | Vài phút
1,000 – 10,000 features | Line / Point | Dưới 1 phút
> 10,000 features | Polygon | 5-15 phút (Missing Nodes tự skip nếu >200)
> 10,000 features | Line / Point | 1-5 phút

# 8. Xử lý lỗi thường gặp

Vấn đề | Nguyên nhân | Giải pháp
--- | --- | ---
Progress bar đứng 0% | Layer quá lớn | Chờ thêm hoặc chia nhỏ layer
Fix xong nhưng còn lỗi | Cascade effect | Chạy lại kiểm tra + sửa lần 2
Highlight không hiện | Layer bị ẩn | Bật visibility trong Layers panel
Missing Nodes bị skip | >200 features (O(n²)) | Chia layer thành vùng nhỏ hơn
Kết quả không mở được | File bị lock | Đóng file trong ứng dụng khác
Dangle/Isolated = lỗi giả | Đặc thù dữ liệu | Bỏ tick Fix, chỉ review thủ công