Use the same workflow to handle web map coordinates, coordinate tables, Shapefiles, and CAD files. First confirm the geometry, fields, and coordinate reference, then perform the conversion and verify the output.
Security boundaries
- Do not arbitrarily determine a unique coordinate system based on numeric ranges, and do not automatically add a Gauss zone number to X/Y.
- "Chengdu coordinate system" and other local independent coordinates can be written into SHP/DXF/DWG at their original values, and use
LOCAL_CSto mark the source; this does not mean that a conversion relationship to CGCS2000, WGS84, or online basemaps has been obtained. - Only after obtaining a formal EPSG/PRJ, central meridian and zone number, conversion parameters, or public control points should conversion between local coordinates and national coordinates be performed.
- Data in the same local coordinate system can be directly overlaid; to overlay with online basemaps or other coordinate systems, reliable registration must first be completed.
- When it is necessary to determine projected coordinates or local coordinates, first read references/projected-and-local-crs.md。
Workflow routing
| Task | Tool | Description |
|---|---|---|
| WGS84 / GCJ02 / BD09 mutual conversion | scripts/convert.py |
Supports single points, lists, and CSV/TSV/GeoJSON/GPX/KML |
| Convert XLSX/CSV coordinate tables to SHP | scripts/tabular_to_shapefile.py |
Outputs a ZIP containing SHP/SHX/DBF/PRJ/CPG, field mappings, and a report |
| Convert SHP to DXF | scripts/shapefile_to_dxf.py |
Supports points, lines, polygons, and multipoints, preserves Z; can generate text labels by field |
| Convert DXF to DWG | scripts/dxf_to_dwg.py |
Calls ODA File Converter by default, and enforces DWG→DXF round-trip auditing |
| Overlay screenshots onto KML polygons | scripts/kml_image_overlay.py |
Select target polygons and output a portable KMZ with embedded images |
The table and Shapefile tools require installing dependencies:
python3 -m pip install -r resources/requirements.txt
Generate Shapefile from coordinate table
First check the worksheet name, X/Y/Z columns, record count, and coordinate range. Local coordinates only need to be labeled with a name, without unverified numeric transformation:
python3 scripts/tabular_to_shapefile.py input.xlsx \
--sheet Sheet1 \
--x-col X --y-col Y --z-col High \
--local-crs-name "Chengdu City Coordinate System" \
-o output_shapefile.zip
Already obtained formal .prj when, use instead:
python3 scripts/tabular_to_shapefile.py input.csv \
--x-col Easting --y-col Northing --z-col Elevation \
--prj-file authoritative.prj \
-o output_shapefile.zip
When the EPSG code has been confirmed, you can also directly generate a standard .prj：
python3 scripts/tabular_to_shapefile.py input.csv \
--x-col 经度 --y-col 纬度 \
--epsg 4326 \
-o output_shapefile.zip
--epsg、--prj-file and --local-crs-name must and can only choose one. By default, stop upon encountering invalid coordinates; only after confirming that discarding abnormal rows is allowed, use --skip-invalid. The output ZIP contains a field name mapping CSV and a conversion report JSON, used to trace the 10-character field name limit of DBF.
Export Shapefile to DXF / DWG
First extract the complete Shapefile components, then generate DXF:
python3 scripts/shapefile_to_dxf.py input.shp \
--layer SURVEY_POINT \
--label-field PointName \
-o output.dxf
DWG is not a pure Python native format. Deliverable DWG must be generated by ODA File Converter; the script enables ODA auditing, converts the generated DWG back to DXF, then compares entity types, layers, 3D extents, and performs ezdxf auditing. If any check fails, the target file will not be replaced:
ODA File Converter needs to be obtained from the official Open Design Alliance pageand installed separately.
# 自动查找 ODAFileConverter；不会自动回退到 LibreDWG
python3 scripts/dxf_to_dwg.py output.dxf -o output.dwg \
--report output_validation.json
# 明确指定命令行程序；macOS 也可以直接指定 .app 包
python3 scripts/dxf_to_dwg.py output.dxf -o output.dwg \
--converter oda --converter-path /path/to/ODAFileConverter \
--version r2000 --report output_validation.json
Only when compatibility risks are explicitly accepted and it is used only for internal experiments may --converter libredwgbe explicitly passed in. This kind of output will be marked as experimental-not-for-delivery, and cannot be delivered externally merely because LibreDWG itself can read it back.
The complete business attributes of SHP are retained in the DBF; DXF/DWG mainly carries geometry and optional text annotations. The script copies files with the same name .prj sidecar files, but CAD files themselves usually do not fully express GIS coordinate references.
Overlay screenshot onto KML polygon
When there is only one polygon in the KML, you can run directly:
python3 scripts/kml_image_overlay.py area.kml screenshot.png \
-o area_overlay.kmz
When there are multiple polygons, select by Placemark name or by a 1-based index:
python3 scripts/kml_image_overlay.py area.kml screenshot.jpg \
--polygon-name "目标区域" --opacity 0.85 \
-o area_overlay.kmz
For a convex quadrilateral where the orientation of the four corners can be uniquely determined, use gx:LatLonQuad by default for precise fitting; when the orientation is ambiguous or it is not a convex quadrilateral, transparent clipping is used automatically. For maximum KML software compatibility, pass --mode clip. Before processing, read references/kml-image-overlays.md, and confirm that the polygon is in WGS84 longitude/latitude and that the screenshot orientation is north-up, south-down.
Web map coordinate conversion
The following identifiers are supported:
| Identifier | Common aliases | Purpose |
|---|---|---|
wgs84 |
gps、wgs |
GPS / international longitude and latitude |
gcj02 |
高德、腾讯、火星 |
Mainland China web map offset coordinates |
bd09 |
百度、bd |
Baidu Map coordinates |
# 单点，默认 lon,lat
python3 scripts/convert.py -f wgs84 -t gcj02 116.3974,39.9093
# 文件模式，自动识别 CSV 经纬度列并保留其余字段
python3 scripts/convert.py -f wgs84 -t bd09 -i points.csv -o points_bd09.csv
# 手动指定列名
python3 scripts/convert.py -f 高德 -t wgs84 -i points.tsv \
--lon-col 经度 --lat-col 纬度
File mode supports CSV, TSV, GeoJSON, GPX, and KML; point mode supports --lat-first、--format text|csv|json and --precision. The core algorithm is located in scripts/coordinate_converter.py, and depends only on the standard library.
Verification checklist
Before delivery, at least check:
- The number of output features matches the number of valid input rows; if abnormal rows are skipped, there is a clear count in the report.
- The X/Y minimum and maximum values match the source data; the Z range and null value policy of PointZ meet expectations.
- The SHP can be read again, and
.shp、.shx、.dbf、.prj、.cpgare complete. - The verification report for a deliverable DWG must be
deliveryStatus: validated, and pass ODA round-trip audit, entity type, layer, and 3D bounding box comparison; only having a correct DWG file header does not count as passing verification. - Clearly inform the user: whether the data is "local coordinates retained" or "converted to standard coordinates that can be overlaid on a map".