If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/AndrewHartAR/ARKit-CoreLocation shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5w ago
• 11 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live AndrewHartAR/ARKit-CoreLocation repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/AndrewHartAR/ARKit-CoreLocation.

What it runs against: a local clone of AndrewHartAR/ARKit-CoreLocation — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in AndrewHartAR/ARKit-CoreLocation | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 62 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of AndrewHartAR/ARKit-CoreLocation. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/AndrewHartAR/ARKit-CoreLocation.git
#   cd ARKit-CoreLocation
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of AndrewHartAR/ARKit-CoreLocation and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "AndrewHartAR/ARKit-CoreLocation(\\.git)?\\b" \\
  && ok "origin remote is AndrewHartAR/ARKit-CoreLocation" \\
  || miss "origin remote is not AndrewHartAR/ARKit-CoreLocation (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "ARKit+CoreLocation/POIViewController.swift" \\
  && ok "ARKit+CoreLocation/POIViewController.swift" \\
  || miss "missing critical file: ARKit+CoreLocation/POIViewController.swift"
test -f "ARKit+CoreLocation/POIViewController+ARSCNViewDelegate.swift" \\
  && ok "ARKit+CoreLocation/POIViewController+ARSCNViewDelegate.swift" \\
  || miss "missing critical file: ARKit+CoreLocation/POIViewController+ARSCNViewDelegate.swift"
test -f "ARKit+CoreLocation/LocationCell.swift" \\
  && ok "ARKit+CoreLocation/LocationCell.swift" \\
  || miss "missing critical file: ARKit+CoreLocation/LocationCell.swift"
test -f "ARCLTests/CLLocationExtensionsTests.swift" \\
  && ok "ARCLTests/CLLocationExtensionsTests.swift" \\
  || miss "missing critical file: ARCLTests/CLLocationExtensionsTests.swift"
test -f "ARCL.podspec" \\
  && ok "ARCL.podspec" \\
  || miss "missing critical file: ARCL.podspec"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 62 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~32d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/AndrewHartAR/ARKit-CoreLocation"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ARKit + CoreLocation fuses Apple's ARKit (local camera/motion-based 3D mapping) with CoreLocation (GPS/WiFi positioning) to place real-world geolocated objects into augmented reality scenes with meter-level accuracy at scale. It solves the fundamental problem that ARKit alone is accurate only within a small local space, while GPS alone lacks precision—this library bridges them by anchoring AR objects using real-world GPS coordinates and improving location accuracy through AR-tracked movement. Monolithic Xcode project structure: ARKit+CoreLocation/ contains the main framework code; ARCLTests/ holds unit tests (CLLocationExtensionsTests.swift visible); demo app and framework coexist in single workspace. ARCL.podspec at root exposes the library for CocoaPods distribution.

iOS developers building location-based AR applications (tourism apps, navigation overlays, geospatial visualization, points-of-interest discovery) who need to display spatially-anchored digital content relative to real GPS coordinates without losing AR precision.

Actively maintained but pre-1.0 experimental phase. The repo has CI/CD via Travis, a CocoaPods package (ARCL), Carthage support, and unit tests (ARCLTests/), but core location-accuracy improvements remain explicitly marked 'experimental' in the README. Production-ready for basic AR+GPS placement; use caution on location-accuracy features pending community feedback.

Single-maintainer risk (Andrew Hart / ProjectDent org). No recent commit dates visible in file structure, and the experimental location-accuracy feature is incomplete. Dependencies appear minimal (mostly Apple frameworks), but lacking comprehensive test coverage for the delicate AR-GPS fusion logic. iOS 11+ requirement means older device drop-off.

No specific commit or PR data visible in file list; Slack community referenced in README suggests active user discussion despite minimal visible dev activity. True North calibration section mentioned in README indicates recent docs work, but no specific current milestones or open PRs enumerated.

git clone https://github.com/AndrewHartAR/ARKit-CoreLocation.git
cd ARKit-CoreLocation
open ARKit+CoreLocation.xcworkspace

Then select the ARKit+CoreLocation scheme in Xcode and build (iOS 11+ target device/simulator required).

Daily commands: Open ARKit+CoreLocation.xcworkspace in Xcode (not the .xcodeproj), select a physical iOS 11+ device or ARKit-compatible simulator, and press Run. Demo app will display AR anchors at geolocation-specified positions.

• ARKit+CoreLocation/POIViewController.swift — Primary view controller that orchestrates ARKit camera rendering with CoreLocation GPS data; implements the core happy-path for displaying points of interest in AR space.
• ARKit+CoreLocation/POIViewController+ARSCNViewDelegate.swift — Delegates ARSCNView rendering and scene updates; critical for converting GPS coordinates to AR node positions in real-world space.
• ARKit+CoreLocation/LocationCell.swift — Data model and UI representation for location objects; essential for understanding how POI data flows through the app.
• ARCLTests/CLLocationExtensionsTests.swift — Test suite for coordinate transformation logic; validates the mathematical foundations of GPS-to-AR conversion.
• ARCL.podspec — CocoaPods specification defining the library's public API, dependencies, and distribution metadata.
• ARKit+CoreLocation/Utils.swift — Utility functions for coordinate math, distance calculations, and spatial transformations between GPS and AR coordinate systems.
• Podfile — Dependency manifest; defines all third-party libraries and their versions required for the project.

• POIViewController (UIViewController, ARSCNView, CLLocationManager, SCNScene) — Orchestrator that bridges ARKit session state and CoreLocation updates; owns the ARSCNView and delegates AR rendering to POIViewController+ARSCNViewDelegate.
  • Failure mode: If ARKit initialization fails (unsupported device) → shows NotSupportedViewController; if CoreLocation permission denied → warns user.
• ARSCNViewDelegate (POIViewController+ARSCNViewDelegate) (ARSCNViewDelegate, SCNNode, Transform math) — Implements ARSCNViewDelegate protocol to intercept renderer callbacks; creates and updates SCNNode positions based on GPS bearing and device pose.
  • Failure mode: If coordinate math produces NaN/Inf → nodes fail to render; requires Utils.swift validation.
• Utils — undefined

Add a new Point of Interest (POI) type

1. Define a new POI data model by extending LocationCell.swift with a new location type property. (ARKit+CoreLocation/LocationCell.swift)
2. Create a new ARSCNNode subclass or configure nodes in POIViewController+ARSCNViewDelegate.swift's node-creation logic. (ARKit+CoreLocation/POIViewController+ARSCNViewDelegate.swift)
3. Add distance/bearing calculation helpers in Utils.swift if your POI type requires custom positioning logic. (ARKit+CoreLocation/Utils.swift)
4. Integrate the new POI source (API, local database) in POIViewController.swift's location-update handler. (ARKit+CoreLocation/POIViewController.swift)
5. Write unit tests following the pattern in CLLocationExtensionsTests.swift to validate coordinate transforms. (ARCLTests/CLLocationExtensionsTests.swift)

Add a new AR rendering feature (e.g., overlays, animations)

1. Implement your rendering logic in POIViewController+ARSCNViewDelegate.swift's delegate methods (e.g., renderer:didAdd:for:). (ARKit+CoreLocation/POIViewController+ARSCNViewDelegate.swift)
2. Expose user controls in SettingsViewController.swift to toggle the feature on/off. (ARKit+CoreLocation/SettingsViewController.swift)
3. Test the feature in a demo project by modifying Node Demos/ARCLViewController.swift. (Node Demos/ARCLViewController.swift)

Publish a new version of the ARCL library

1. Update version string in ARCL.podspec and commit changes. (ARCL.podspec)
2. Tag the commit in git with the new version (e.g., git tag v1.2.3). (.travis.yml)
3. CI/CD (Travis) will automatically verify the build; push to CocoaPods registry once tests pass. (Podfile)

• ARKit (Vision + Motion APIs) — Provides real-time 6-DOF camera pose and scene understanding at centimeter scale; forms the spatial foundation for AR rendering.
• CoreLocation (CLLocationManager) — Delivers GPS coordinates and heading data at global scale; enables fusion with ARKit's local coordinate system.
• SceneKit (SCNView, SCNNode) — High-level 3D rendering engine integrated with ARKit; simplifies node placement and animation in AR space.
• CocoaPods + Swift Package Manager — Distributes the library as both a pod and SPM package; broadens adoption across iOS ecosystem.

• Use GPS + ARKit fusion rather than pure SLAM for global positioning

  • Why: SLAM-only systems drift over distance; GPS provides global ground-truth correction every 1–10 seconds.
  • Consequence: GPS accuracy (~5–20m) limits precision of distant POIs; requires smart bearing-based culling to avoid screen clutter.

• Immutable SCNNode tree with transform updates rather than scene graph rebuilds

  • Why: Avoids expensive scene graph regeneration on every location update.
  • Consequence: Requires careful management of node state and animation scheduling; potential for animation jank if updates happen too frequently.

• Single-view AR architecture (POIViewController) rather than modular AR components

  • Why: Simpler to prototype and understand; fewer abstractions for beginners.
  • Consequence: Harder to reuse AR logic across multiple screens; custom integration required for complex multi-scene apps.

• Real-time multiplayer AR (no networking layer)
• 3D mesh reconstruction or environment mapping (uses ARKit's session data only)
• Support for macOS or tvOS (iOS/ARKit only)
• Machine learning-based POI detection (manual coordinate input required)
• Offline GPS fallback (requires live CoreLocation updates)

True North calibration required: README explicitly warns that magnetic north can drift; apps must implement magnetometer-based calibration or use visual features to correct heading. Device hardware variance: Not all iOS 11 devices support ARKit equally (iPhone 6S vs later models have different SLAM quality). GPS accuracy degradation indoors: CoreLocation loses signal in buildings; the AR location-improvement system must gracefully degrade. No explicit location privacy checks visible: Ensure NSLocationWhenInUseUsageDescription and NSCameraUsageDescription in Info.plist (not visible in file list—common gotcha).

• SLAM (Simultaneous Localization and Mapping) — ARKit's SLAM engine maps the local 3D world in real-time; understanding its limitations (drift over distance) is critical to why GPS fusion is necessary.
• Coordinate Frame Transformation (World → Local AR Space) — The core challenge: converting WGS84 GPS coordinates to local ARWorldTrackingConfiguration anchor positions; requires matrix math and understanding AR's local reference frame.
• Magnetic Declination & True North Calibration — GPS north and magnetic north differ geographically; ARKit uses device heading (magnetometer), so calibration ensures AR objects align with actual world bearings.
• Particle Filter / Dead Reckoning — Likely algorithm for the 'experimental' location-accuracy improvement: fuses noisy GPS with AR-tracked motion to estimate true position better than GPS alone.
• CLLocationManager Delegate Pattern — CoreLocation delivers async GPS/WiFi updates; library must implement CLLocationManagerDelegate to react to location changes without blocking ARKit rendering.
• Geodetic Distance (Haversine Formula) — Calculating real-world distance between two GPS coordinates (used in CLLocationExtensionsTests.swift) is non-trivial on a sphere; affects AR object placement distance calculation.

• Mapbox/mapbox-gl-native — Alternative for rendering geospatial data on maps; complementary for apps needing both AR overlays and traditional map views.
• apple/swift-arkit-samples — Official Apple ARKit examples; foundational ARWorldTrackingConfiguration patterns that this library builds on.
• maxvol/ARKitSceneKitDemo — Community ARKit + SceneKit demo showing similar local 3D placement techniques; reference implementation for AR scene graph management.
• ProjectDent/Meerkat — Sibling project from same author exploring AR visualization; likely uses or influenced by ARKit-CoreLocation patterns.
• willow-ai/ml-sdk-ios — ML-based heading/GPS improvement for iOS; complementary sensor fusion approach to solving the location-accuracy problem this library targets.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for CLLocationExtensions

ARCLTests/CLLocationExtensionsTests.swift exists but is likely incomplete given the CoreLocation integration is core to this library. The repo lacks comprehensive test coverage for location calculations, coordinate transformations, and distance computations that are critical for AR-GPS accuracy.

• [ ] Review existing CLLocationExtensionsTests.swift to identify gaps
• [ ] Add tests for coordinate transformation methods used in AR positioning
• [ ] Add tests for distance/bearing calculations between GPS points
• [ ] Add tests for location validation and edge cases (equator, dateline, poles)
• [ ] Ensure tests run in .travis.yml CI pipeline

Add GitHub Actions workflow to replace/supplement Travis CI

The repo uses .travis.yml (outdated CI) but GitHub Actions is now the standard for GitHub-hosted projects. Modern actions provide better integration, faster feedback, and native GitHub UI. This improves contributor experience and modernizes the development workflow.

• [ ] Create .github/workflows/swift-build-test.yml workflow file
• [ ] Configure matrix for multiple iOS SDK versions and Xcode versions
• [ ] Add SwiftLint step (integration already exists: .swiftlint.yml)
• [ ] Add CocoaPods pod spec lint step (ARCL.podspec exists)
• [ ] Migrate .travis.yml configuration to GitHub Actions format
• [ ] Remove or deprecate .travis.yml after validation

Extract and document ARKit+CoreLocation coordination logic into a separate Core module

POIViewController.swift and POIViewController+ARSCNViewDelegate.swift handle the complex AR scene coordination. This logic is mixed with view controller concerns and would benefit contributors by being isolated. Creating a documented coordinator module would clarify the AR-GPS integration architecture.

• [ ] Create ARKit+CoreLocation/ARGPSCoordinator.swift to encapsulate AR scene coordinate calculations
• [ ] Extract location-to-ARWorldMap transformation logic from POIViewController+ARSCNViewDelegate.swift
• [ ] Document coordinate system conversions (GPS WGS84 ↔ ARKit local coordinates) with inline comments
• [ ] Add unit tests for ARGPSCoordinator in ARCLTests/
• [ ] Update POIViewController to delegate to ARGPSCoordinator, reducing its complexity
• [ ] Add architectural documentation to README explaining the coordination flow

• Add unit tests for CLLocation+Bearing or similar math extensions in ARCLTests/; the test file exists but likely lacks comprehensive coverage of coordinate-to-AR-anchor conversions.
• Document the True North calibration algorithm in a new CALIBRATION.md file, with code example showing how to use magnetometer data to correct initial heading; README hints at this but provides no runnable example.
• Extract and test the location-accuracy improvement logic (currently 'experimental') into a separate, well-tested module with before/after GPS accuracy metrics; structure the module for community contribution.

This is an iOS/Swift library project with moderate security posture. No critical vulnerabilities are immediately apparent from the file structure. The project uses SwiftLint for code quality (positive signal). Main concerns are: (1) dependency management requires deeper analysis of Gemfile/CocoaPods dependencies, (2) location/PII data handling practices need documentation, (3) lack of visible security testing, and (4) standard CI/CD configuration best practices around secrets management. The codebase appears well-organized with proper project structure. Recommend implementing dependency vulnerability scanning, security testing, and privacy documentation.

• Medium · Missing dependency version lockfile analysis — Gemfile, Gemfile.lock. The Gemfile and Gemfile.lock are present but content was not provided for analysis. Ruby dependencies should be reviewed for known vulnerabilities using tools like bundler-audit. Fix: Run 'bundle audit' to check for vulnerable gem versions. Ensure all dependencies are pinned to specific versions and regularly updated.
• Low · Potential sensitive configuration in project files — .travis.yml. The .travis.yml file may contain sensitive build or deployment information. Travis CI configuration files can accidentally expose secrets through environment variables or credentials. Fix: Audit .travis.yml for any hardcoded secrets, API keys, or credentials. Use Travis CI's secure environment variable feature for sensitive data. Never commit secrets to version control.
• Low · Missing HTTPS enforcement documentation — Project configuration and network communication code. This is a library that combines AR with GPS/CoreLocation. No evidence of HTTPS enforcement for network communications in the provided file structure. Fix: Ensure all network requests use HTTPS/TLS. If the library makes API calls, verify that certificate pinning is implemented for sensitive endpoints. Document security requirements for library users.
• Low · Location data privacy considerations — ARKit+CoreLocation/POIViewController.swift, CLLocationExtensionsTests.swift. The library handles GPS location data which is sensitive personally identifiable information (PII). No explicit privacy policy or data handling documentation visible in the file structure. Fix: Document how location data is handled, transmitted, and stored. Implement appropriate privacy controls. Ensure compliance with GDPR, CCPA, and app store privacy requirements. Request explicit user consent for location access.
• Low · No visible security test coverage — ARCLTests/, Node DemosTests/, Node DemosUITests/. Test files visible (ARCLTests, Node DemosTests, Node DemosUITests) but no dedicated security or vulnerability testing framework is evident. Fix: Implement security-focused unit tests. Use static analysis tools like SwiftLint (already configured) and add runtime security checks. Consider OWASP Mobile Top 10 for iOS-specific vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.