From Compass Charting to Auditable Spatial Decision Support: Multi-source Geospatial Fusion, Pai Long Computation, and Human-in-the-loop Design of the Xuan Kong Map Workbench

Article type: Research paper / system design and technical verification report
System version: xk-autodragon 0.1.0; app 20260421e; algorithm pailong_v4_five_auspicious_palace_coverage
Review status: Internal technical paper; not independently peer-reviewed or field-validated

Research statement: This paper evaluates structural consistency and auditability under the encoded rules. Software tests do not establish the modern scientific causal efficacy of traditional practices, and online geospatial data do not replace field measurement or professional judgment.

Abstract

Most digital Xuan Kong tools begin with a compass reading or a manually entered orientation and then generate a Twenty-four Mountains or Flying Stars chart. The Xuan Kong Map Workbench prototype extends this workflow by joining geospatial context acquisition, road-network-based water-mouth candidate generation, building-footprint and entrance inference, Pai Long computation, Flying Stars charting, and explainable orientation ranking in one auditable pipeline. Following a design-science approach, this paper documents the artefact, its rule boundaries, and reproducible structural verification.

The current verification covers 36,000 bearing samples at 0.01-degree intervals, 24 water-mouth mountain centres, a 180-year period cycle, 432 house-chart combinations, and synthetic road/building scenarios. All defined software invariants passed. These checks establish deterministic consistency under the encoded rules; they do not validate real-world feng shui efficacy, the field accuracy of third-party data, or causal effects on occupants. The principal contribution is integrative and governance-oriented: the workbench moves from isolated chart calculation to contextual spatial analysis, preserves data and rule provenance, exposes intermediate scores and degree boundaries, and keeps manual expert correction inside the workflow.

Keywords: Xuan Kong feng shui; GIS; Pai Long; Flying Stars; Twenty-four Mountains; geospatial data fusion; explainable decision support; human-in-the-loop systems

1. Research Scope and Questions

Feng shui can be studied as a historically developed body of spatial knowledge, architectural culture, and professional practice. It is also frequently marketed as a predictive method with certain causal effects. These claims must be kept separate. Existing studies have used GIS, spatial regression, remote sensing, and landscape-character models to formalise and compare feng shui-related concepts in tomb siting, cultural landscapes, and heritage research [1–3]. Such work demonstrates that traditional spatial vocabularies can be represented and measured; it does not mean that every school or practical claim has been scientifically validated.

This study addresses an information-systems problem: how can a practitioner move from an address to a reviewable assessment of water-mouth candidates, building geometry, and orientation without repeatedly transferring data among maps, compasses, charts, and notes—and without allowing automation to disguise assumptions as facts?

1. How can roads, building footprints, entrance information, and traditional directional rules be joined in one repeatable pipeline?
2. How can true/magnetic north, raw bearings, Twenty-four Mountains boundaries, data sources, and algorithm versions remain traceable?
3. How can automated candidates narrow the field for professional review without replacing field measurement and school-specific judgment?
4. Before a field-validity dataset exists, which conclusions can structural software verification support and which must remain hypotheses?

2. Method and Evidence Boundaries

The study follows a design-science approach [4]. Work proceeded through software component inventory, reconstruction of the rule chain, repeatable invariant testing, and a limitation review separating internal software consistency, third-party data quality, traditional-rule interpretation, and real-world effects.

3. System Architecture

3.1 End-to-end workflow

Target location → road/building data acquisition → water-mouth candidate generation or manual designation → batch building analysis → footprint, facing and entrance inference → Pai Long matrix → two-point or manually overridden orientation → standard/substitute Flying Stars chart → candidate-orientation ranking → degree and provenance audit.

The workflow deliberately keeps two bearings separate. Pai Long uses the bearing from the building centre to the selected water-mouth candidate; Flying Stars uses the building's sitting/facing orientation. Both are shown independently to prevent the water-mouth direction from being mistaken for the house orientation.

3.2 Multi-source geospatial layer

• OpenStreetMap / Overpass: road networks and community-maintained building features, subject to ODbL attribution requirements [10].
• Overture Maps Buildings: supplementary footprints, classification, names, and source records; a single building may merge multiple upstream sources [11].
• Google Geocoding API v4 SearchDestinations: supplementary display polygons, entrances, and navigation points rather than presumed ground truth [12].

Source labels are retained through merging so that OSM, Overture, and Google-derived evidence can be distinguished and later evaluated separately. GeoJSON coordinates follow WGS 84. As RFC 7946 notes, additional decimal places do not themselves establish measurement accuracy [9].

3.3 Bearings and magnetic correction

The system defines north as 0° and east as 90°, normalising bearings to [0°, 360°). Conversion from true to magnetic north is:

Magnetic bearing = (true bearing − magnetic declination) mod 360°

Magnetic declination δ is entered by the user. The current version does not retrieve a time- and location-dependent declination automatically, so the value, date, and source should be recorded. A value of δ = 0 means that no magnetic correction has been applied.

3.4 Road-network water-mouth proxy

The current algorithm is not a hydrological model. It extracts road intersections and bends meeting a turn-angle threshold, merges nearby nodes, and ranks them as reviewable proxy candidates:

S_w = 0.20D + 0.22R + 0.18T + 0.15L + 0.08V + 0.10N + 0.07C

D represents distance, R road class, T intersection/bend structure, L connected-segment scale, V directional visibility, N connected-road count, and C candidate type. The default bend threshold is 35°. A road node may be relevant to traditional water-mouth assessment—or entirely irrelevant. Terrain, waterways, drainage, sight lines, bridges, access controls, and actual site conditions may change the conclusion. The interface therefore retains the candidate list and manual designation.

3.5 Facing and entrance inference

For each building polygon, the system calculates centroid, edge length, edge orientation, and outward bearing, then compares the edge with nearby roads. The road-match score is:

S_r = 0.40P + 0.30D_r + 0.20F + 0.10R_c

P is parallel alignment, D_r road proximity, F the degree to which the facade faces the road, and R_c road class. The facade score is:

S_f = 0.35L_e + 0.65S_r

where L_e is relative edge length. Entrance candidates combine facade evidence, road alignment, centrality along the edge, and road distance:

S_e = 0.45S_f + 0.30A + 0.15C_e + 0.10D_e

This supports plausible first-pass interpretation for regular street-facing buildings. It is less reliable for corner buildings, podium-and-tower complexes, campuses, shopping centres, historic buildings, and properties with multiple entrances. Field use remains decisive.

3.6 Pai Long, Flying Stars, and ranking

Each of the Twenty-four Mountains spans 15°. Half-open intervals avoid assigning a boundary bearing to two mountains. The bearing from building centre to water mouth is reversed by 180° to obtain the incoming-dragon direction. Directional polarity controls forward or reverse placement of the twelve-step sequence. Under the current rule set, You Bi, Wu Qu, Tan Lang, Zuo Fu, and Ju Men are marked as auspicious, producing five candidate palaces and ten candidate sitting mountains per Pai Long matrix.

The Flying Stars module is separate. It accepts period, sitting mountain, and chart mode, then outputs period, mountain, and facing stars across nine palaces. Modes include standard and substitute charts. The Three Cycles and Nine Periods calculation uses 1864 as the start of a 180-year cycle, with twenty years per period.

Candidate orientation combines Pai Long priority (35%), facade evidence (25%), entrance evidence (15%), water-mouth evidence (15%), and chart-mode confidence (10%). If a component is missing, remaining weights are renormalised rather than treating missing evidence as zero. These weights are engineering heuristics, not empirically calibrated probabilities.

4. Structural Verification

These tests demonstrate repeatable, internally complete output for identical inputs under the encoded rules. They do not show that a road proxy equals a field-observed water mouth, quantify disagreement between inferred and expert-measured facing, or establish causal effects on occupants or businesses.

5. Innovation and Industry Relevance

• From chart calculator to contextual spatial workbench: address, roads, buildings, candidate water mouths, and entrances are incorporated before chart generation.
• From answer delivery to evidence-chain audit: raw bearings, magnetic correction, mountain boundaries, palace placement, source labels, component weights, and algorithm versions remain inspectable.
• Multi-source complementarity: sources are combined without erasing their different coverage, provenance, and licensing conditions.
• Human-in-the-loop design: practitioners can designate water mouths manually, override orientation, and perform two-point measurement. Automation narrows the review space instead of pretending to eliminate ambiguity.
• Versioned traditional rules: boundary conventions, north reference, chart mode, missing-data handling, and school-specific matrices become explicit and comparable.

Potential applications include preliminary screening, professional site-survey preparation, teaching and transmission, and the construction of consented, de-identified research datasets. No time-and-motion study, user study, conversion experiment, or field-accuracy study has yet established quantified commercial benefits.

6. Limitations and Research Agenda

1. No field gold-standard dataset currently supports accuracy, recall, or inter-expert agreement claims.
2. Road structure is not hydrology; elevation, waterways, drainage, visibility, and site access remain unmodelled.
3. A building footprint does not reveal actual use. Geometric frontage and mapped entrances may differ from the operational main entrance or receiving face.
4. Small errors near Twenty-four Mountains boundaries may change mountain assignment and chart mode. Boundary warnings and uncertainty intervals are needed.
5. Heuristic weights have not been calibrated on labelled examples.
6. The implementation represents a specific Pai Long matrix and Zhongzhou-style Flying Stars workflow, not universal agreement among all schools.
7. Coverage, API maturity, quotas, terms, and licence requirements vary by region and over time.
8. Precise residential locations and survey records may be sensitive. Public research should be de-identified and must not substitute for regulated professional advice.

Future work should build a stratified field dataset, measure facing-angle mean absolute error and 95th-percentile error, evaluate water-mouth Top-1/Top-3/Top-5 recall, assess entrance-point distance error and inter-rater agreement, compare sources, test stability under ±1°/±2°/±3° perturbations, and conduct weight sensitivity analysis. Expert annotation should be blinded to system ranking and the evaluation protocol should be preregistered.

7. Conclusion

The Xuan Kong Map Workbench demonstrates a path beyond placing a compass chart on a screen. It connects address search, road and building context, water-mouth proxies, orientation, Pai Long, Flying Stars, and candidate ranking in an auditable spatial workflow. Its most defensible present contribution is making implicit rules repeatable, exposing intermediate assumptions, constraining automation to candidate generation and consistent computation, and preserving the professional user's ability to review and override.

Structural verification confirms internal consistency in directional partitioning, Pai Long matrices, the period cycle, Flying Stars permutations, and score normalisation. It is not evidence of field validity or modern scientific causal efficacy. With de-identified field samples, blinded review, explicit error metrics, sensitivity analysis, and version governance, the system could become shared infrastructure for digital geomancy research, professional education, and responsible service design.

References

1. Um, J.-S. (2009). Exploring spatially prioritized parameters of Feng-Shui from tomb footprint. International Journal of Geographical Information Science, 23(4), 513–529. DOI.
2. Zhao, Y., Harvey, D. C., & Gao, C. (2020). Identifying Shan-Shui characteristics for national landscape heritage. The Geographical Journal, 186, 300–313. DOI.
3. Cui, J., Liu, Y., Sun, J., Hu, D., & He, H. (2021). Study on Feng Shui (Geomantic) Suitability Evaluation of Mausoleums in Nanjing City Based on GIS. ISPRS International Journal of Geo-Information, 10(11), 752. DOI.
4. Peffers, K. et al. (2007). A Design Science Research Methodology for Information Systems Research. Journal of Management Information Systems, 24(3), 45–77. DOI.
5. QiPlus. Qi+ Feng Shui Software — Features. Product page.
6. Feng Shui Magazine Ltd. FSML Professional Feng Shui Software Tool. Product page.
7. Google Play. Flying Stars Feng Shui — App listing. App listing.
8. Global Feng Shui Association (2026). Academic and Research Governance Standards 2.0. Governance standard.
9. Butler, H. et al. (2016). RFC 7946: The GeoJSON Format. IETF. RFC 7946.
10. OpenStreetMap Foundation. Copyright and License. Licence page.
11. Overture Maps Foundation. Building Schema Reference. Specification.
12. Google Maps Platform. Search for destinations — Geocoding API v4. Official documentation.

Appendix: Reproducibility and Disclosure

• Research artefact: xk-autodragon 0.1.0
• Code baseline: Git commit 161a305
• Backend version: 20260421e
• Algorithm version: pailong_v4_five_auspicious_palace_coverage
• Verification date: 2026-09-04
• Verification script: research/validate_xk_workbench.py

Review status: This is a system-design and internal technical-verification paper. It has not been independently peer-reviewed or field-validated.

Conflict disclosure: The paper examines a prototype developed or operated by the publishing organisation. System demonstration and research communication are directly related, and readers should interpret innovation claims accordingly.

AI-use disclosure: On 2026-09-04, OpenAI Codex (GPT-5 series) assisted with code-structure synthesis, drafting, and formatting. Bearings, weights, version identifiers, and verification outcomes derive from local source code and a repeatable script. Named authors and editors remain responsible for the final text.

Use boundary: This paper concerns cultural research and professional workflow design. It does not constitute architectural, planning, surveying, medical, psychological, legal, financial, or other regulated professional advice, and it does not establish causal effects of feng shui judgments on health, wealth, relationships, or other outcomes.