initial file uploading

.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+build
+.git
+.env
+__pycache__
+*.pyc
+*.pyo
+.DS_Store
+coverage

.gitignore

@@ -0,0 +1,35 @@
+# Node.js / React Client
+node_modules/
+client/dist/
+client/build/
+client/coverage/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Python Server
+__pycache__/
+*.py[cod]
+*$py.class
+venv/
+.venv/
+env/
+.pytest_cache/
+
+# C++ SplatTiler
+SplatTiler/build/
+SplatTiler/out/
+*.o
+*.obj
+*.exe
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,59 @@
+# Stage 1: Build C++ Converter (SplatTiler)
+FROM ubuntu:22.04 AS cpp-builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    cmake \
+    zlib1g-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src/SplatTiler
+COPY SplatTiler/ .
+
+# Build the project (Assuming CMakeLists.txt exists in SplatTiler root)
+RUN mkdir build && cd build && cmake .. && make -j$(nproc)
+
+# Stage 2: Build React Client
+FROM node:18-alpine AS client-builder
+
+WORKDIR /src/client
+COPY client/package*.json ./
+RUN npm ci
+
+COPY client/ .
+# Build for production
+RUN npm run build
+
+# Stage 3: Final Server Image
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install runtime dependencies for C++ binary (zlib)
+RUN apt-get update && apt-get install -y \
+    zlib1g \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY server/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy compiled C++ binary from Stage 1
+# Note: Adjust 'SplatTiler' if your binary name differs
+COPY --from=cpp-builder /src/SplatTiler/build/SplatTiler /usr/local/bin/SplatTiler
+
+# Copy built client static files from Stage 2
+COPY --from=client-builder /src/client/dist /app/static
+
+# Copy server code
+COPY server/ .
+
+# Create directory for uploads and converted data
+RUN mkdir -p /app/data/uploads /app/data/converted
+
+# Expose Hugging Face Spaces port
+EXPOSE 7860
+
+# Run FastAPI
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

SplatTiler/CMakeLists.txt

@@ -0,0 +1,25 @@
+cmake_minimum_required(VERSION 3.14)
+
+project(SplatTiler LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(ZLIB REQUIRED)
+
+# Include the root directory so that #include "spz/..." directives work.
+include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+
+add_executable(SplatTiler
+    main.cpp
+    SplatTiler.cpp
+    SplatTiler.h
+    spz/load-spz.cc
+    spz/load-spz.h
+    spz/splat-types.cc
+    spz/splat-types.h
+    spz/splat-c-types.cc
+    spz/splat-c-types.h
+)
+
+target_link_libraries(SplatTiler PRIVATE ZLIB::ZLIB)

SplatTiler/SplatTiler.cpp

@@ -0,0 +1,647 @@
+#include "SplatTiler.h"
+
+#include <algorithm>
+#include <cmath>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <iomanip>
+#include <numeric>
+#include <queue>
+#include <functional>
+#include <limits>
+#include <memory>
+
+#ifndef M_PI
+#define M_PI 3.14159265358979323846
+#endif
+
+namespace tile3dgs {
+
+namespace fs = std::filesystem;
+
+struct AABB {
+    float min[3];
+    float max[3];
+
+    float center(int axis) const { return (min[axis] + max[axis]) * 0.5f; }
+    float size(int axis) const { return max[axis] - min[axis]; }
+    
+    bool contains(float x, float y, float z) const {
+        return x >= min[0] && x <= max[0] &&
+               y >= min[1] && y <= max[1] &&
+               z >= min[2] && z <= max[2];
+    }
+};
+
+struct OctreeNode {
+    AABB aabb;
+    std::vector<int32_t> pointIndices;
+    std::vector<std::unique_ptr<OctreeNode>> children;
+    int depth = 0;
+    int x = 0;
+    int y = 0;
+    int z = 0;
+    std::string filename;
+    float geometricError = 0.0f;
+    
+    bool isLeaf() const { return children.empty(); }
+};
+
+SplatTiler::SplatTiler() {}
+SplatTiler::~SplatTiler() {}
+
+bool SplatTiler::load(const std::string& plyFilename) {
+    spz::UnpackOptions opts;
+    // Load as RDF (Raw) to avoid implicit conversion. We will handle orientation via the matrix.
+    opts.to = spz::CoordinateSystem::RDF;
+    m_cloud = spz::loadSplatFromPly(plyFilename, opts);
+    return m_cloud.numPoints > 0;
+}
+
+// Helper to extract a subset of the cloud
+spz::GaussianCloud extractSubset(const spz::GaussianCloud& source, const std::vector<int32_t>& indices) {
+    spz::GaussianCloud dest;
+    dest.numPoints = static_cast<int32_t>(indices.size());
+    dest.shDegree = source.shDegree;
+    dest.antialiased = source.antialiased;
+
+    if (dest.numPoints == 0) return dest;
+
+    // Reserve memory
+    dest.positions.resize(dest.numPoints * 3);
+    dest.scales.resize(dest.numPoints * 3);
+    dest.rotations.resize(dest.numPoints * 4);
+    dest.alphas.resize(dest.numPoints);
+    dest.colors.resize(dest.numPoints * 3);
+    
+    size_t shTotalPerPoint = 0;
+    if (source.numPoints > 0) {
+        shTotalPerPoint = source.sh.size() / source.numPoints;
+    }
+    dest.sh.resize(dest.numPoints * shTotalPerPoint);
+
+    for (size_t i = 0; i < indices.size(); ++i) {
+        int idx = indices[i];
+        
+        // Copy Position
+        dest.positions[i * 3 + 0] = source.positions[idx * 3 + 0];
+        dest.positions[i * 3 + 1] = source.positions[idx * 3 + 1];
+        dest.positions[i * 3 + 2] = source.positions[idx * 3 + 2];
+
+        // Copy Scale
+        dest.scales[i * 3 + 0] = source.scales[idx * 3 + 0];
+        dest.scales[i * 3 + 1] = source.scales[idx * 3 + 1];
+        dest.scales[i * 3 + 2] = source.scales[idx * 3 + 2];
+
+        // Copy Rotation
+        dest.rotations[i * 4 + 0] = source.rotations[idx * 4 + 0];
+        dest.rotations[i * 4 + 1] = source.rotations[idx * 4 + 1];
+        dest.rotations[i * 4 + 2] = source.rotations[idx * 4 + 2];
+        dest.rotations[i * 4 + 3] = source.rotations[idx * 4 + 3];
+
+        // Copy Alpha
+        dest.alphas[i] = source.alphas[idx];
+
+        // Copy Color
+        dest.colors[i * 3 + 0] = source.colors[idx * 3 + 0];
+        dest.colors[i * 3 + 1] = source.colors[idx * 3 + 1];
+        dest.colors[i * 3 + 2] = source.colors[idx * 3 + 2];
+
+        // Copy SH
+        if (shTotalPerPoint > 0) {
+            const float* srcSH = &source.sh[idx * shTotalPerPoint];
+            float* dstSH = &dest.sh[i * shTotalPerPoint];
+            std::copy(srcSH, srcSH + shTotalPerPoint, dstSH);
+        }
+    }
+
+    return dest;
+}
+
+// Helper to write GLB with embedded SPZ
+void writeGlbWithSpz(const std::string& filename, const std::vector<uint8_t>& spzData, int numPoints, int shDegree, const float* minPos, const float* maxPos) {
+    std::ofstream out(filename, std::ios::binary);
+    
+    // Padding for BIN (must be 4-byte aligned)
+    int paddingBin = (4 - (spzData.size() % 4)) % 4;
+    size_t totalBinSize = spzData.size() + paddingBin;
+
+    // Build dynamic accessors and attributes based on SH degree
+    std::string accessors = "";
+    std::string attributes = "\"POSITION\":0,\"COLOR_0\":1,\"KHR_gaussian_splatting:SCALE\":2,\"KHR_gaussian_splatting:ROTATION\":3";
+    
+    // Standard accessors (0-3)
+    accessors += "{\"componentType\":5126,\"count\":" + std::to_string(numPoints) + ",\"type\":\"VEC3\",\"min\":[" + std::to_string(minPos[0]) + "," + std::to_string(minPos[1]) + "," + std::to_string(minPos[2]) + "],\"max\":[" + std::to_string(maxPos[0]) + "," + std::to_string(maxPos[1]) + "," + std::to_string(maxPos[2]) + "]},"; // POS
+    accessors += "{\"componentType\":5121,\"normalized\":true,\"count\":" + std::to_string(numPoints) + ",\"type\":\"VEC4\"},"; // COLOR
+    accessors += "{\"componentType\":5126,\"count\":" + std::to_string(numPoints) + ",\"type\":\"VEC3\"},"; // SCALE
+    accessors += "{\"componentType\":5126,\"count\":" + std::to_string(numPoints) + ",\"type\":\"VEC4\"}"; // ROTATION
+
+    int accessorIdx = 4;
+    auto addSH = [&](int degree, int count) {
+        for (int i = 0; i < count; ++i) {
+            attributes += ",\"KHR_gaussian_splatting:SH_DEGREE_" + std::to_string(degree) + "_COEF_" + std::to_string(i) + "\":" + std::to_string(accessorIdx++);
+            accessors += ",{\"componentType\":5126,\"count\":" + std::to_string(numPoints) + ",\"type\":\"VEC3\"}";
+        }
+    };
+
+    if (shDegree >= 1) addSH(1, 3);
+    if (shDegree >= 2) addSH(2, 5);
+    if (shDegree >= 3) addSH(3, 7);
+
+    // 1. Prepare JSON
+    // We use a custom extension to indicate this GLB contains SPZ data in the buffer view.
+    std::string jsonStr = 
+        "{"
+        "\"asset\":{\"version\":\"2.0\"},"
+        "\"extensionsUsed\":[\"KHR_gaussian_splatting\",\"KHR_gaussian_splatting_compression_spz_2\",\"KHR_materials_unlit\"],"
+        "\"extensionsRequired\":[\"KHR_gaussian_splatting\",\"KHR_gaussian_splatting_compression_spz_2\"],"
+        "\"buffers\":[{\"byteLength\":" + std::to_string(totalBinSize) + "}],"
+        "\"bufferViews\":[{\"buffer\":0,\"byteOffset\":0,\"byteLength\":" + std::to_string(spzData.size()) + "}],"
+        "\"accessors\":[" + accessors + "],"
+        "\"materials\":[{\"extensions\":{\"KHR_materials_unlit\":{}}}],"
+        "\"meshes\":[{\"primitives\":[{\"mode\":0,\"material\":0,\"attributes\":{" + attributes + "},\"extensions\":{\"KHR_gaussian_splatting\":{\"extensions\":{\"KHR_gaussian_splatting_compression_spz_2\":{\"bufferView\":0}}}}}]}],"
+        "\"nodes\":[{\"mesh\":0,\"matrix\":[1,0,0,0,0,0,-1,0,0,1,0,0,0,0,0,1]}],"
+        "\"scenes\":[{\"nodes\":[0]}],"
+        "\"scene\":0"
+        "}";
+
+    // Padding for JSON (must be 4-byte aligned)
+    int paddingJson = (4 - (jsonStr.size() % 4)) % 4;
+    for(int i=0; i<paddingJson; ++i) jsonStr += ' ';
+
+    // Header
+    uint32_t magic = 0x46546C67; // glTF
+    uint32_t version = 2;
+    uint32_t length = 12 + 8 + (uint32_t)jsonStr.size() + 8 + (uint32_t)totalBinSize;
+
+    out.write((char*)&magic, 4);
+    out.write((char*)&version, 4);
+    out.write((char*)&length, 4);
+
+    // JSON Chunk
+    uint32_t jsonChunkLength = (uint32_t)jsonStr.size();
+    uint32_t jsonChunkType = 0x4E4F534A; // JSON
+    out.write((char*)&jsonChunkLength, 4);
+    out.write((char*)&jsonChunkType, 4);
+    out.write(jsonStr.data(), jsonStr.size());
+
+    // BIN Chunk
+    uint32_t binChunkLength = (uint32_t)totalBinSize;
+    uint32_t binChunkType = 0x004E4942; // BIN
+    out.write((char*)&binChunkLength, 4);
+    out.write((char*)&binChunkType, 4);
+    out.write((char*)spzData.data(), spzData.size());
+    
+    char pad = 0;
+    for(int i=0; i<paddingBin; ++i) out.write(&pad, 1);
+}
+
+// Helper to compute WGS84 transform
+// Returns a 16-element column-major matrix
+std::vector<double> computeTransform(double lat, double lon, double alt) {
+    double a = 6378137.0;
+    double e2 = 0.00669437999014;
+
+    double latRad = lat * M_PI / 180.0;
+    double lonRad = lon * M_PI / 180.0;
+
+    double sinLat = std::sin(latRad);
+    double cosLat = std::cos(latRad);
+    double sinLon = std::sin(lonRad);
+    double cosLon = std::cos(lonRad);
+
+    double N = a / std::sqrt(1.0 - e2 * sinLat * sinLat);
+
+    double x = (N + alt) * cosLat * cosLon;
+    double y = (N + alt) * cosLat * sinLon;
+    double z = (N * (1.0 - e2) + alt) * sinLat;
+
+    // Construct rotation matrix for Z-Up Input (ENU):
+    // Model X (East)  -> East Vector
+    // Model Y (North) -> North Vector
+    // Model Z (Up)    -> Up Vector
+
+    // Up vector (Normal to ellipsoid)
+    double ux = cosLat * cosLon;
+    double uy = cosLat * sinLon;
+    double uz = sinLat;
+
+    // East vector
+    double ex = -sinLon;
+    double ey = cosLon;
+    double ez = 0.0;
+
+    // South vector = -North
+    // North = (-sinLat cosLon, -sinLat sinLon, cosLat)
+    double sx = sinLat * cosLon;
+    double sy = sinLat * sinLon;
+    double sz = -cosLat;
+
+    // Column-major 4x4 matrix
+    return {
+        ex, ey, ez, 0.0,    // X -> East
+        -sx, -sy, -sz, 0.0, // Y -> North
+        ux, uy, uz, 0.0,    // Z -> Up
+        x,  y,  z,  1.0
+    };
+}
+
+void SplatTiler::process(const TileConfig& config) {
+    if (m_cloud.numPoints == 0) {
+        std::cerr << "No points loaded." << std::endl;
+        return;
+    }
+
+    fs::create_directories(config.outputDir);
+
+    // 1. Compute Bounding Box
+    AABB rootAABB = { 
+        {std::numeric_limits<float>::max(), std::numeric_limits<float>::max(), std::numeric_limits<float>::max()},
+        {std::numeric_limits<float>::lowest(), std::numeric_limits<float>::lowest(), std::numeric_limits<float>::lowest()}
+    };
+
+    for (size_t i = 0; i < m_cloud.positions.size(); i += 3) {
+        float x = m_cloud.positions[i];
+        float y = m_cloud.positions[i+1];
+        float z = m_cloud.positions[i+2];
+        
+        rootAABB.min[0] = std::min(rootAABB.min[0], x);
+        rootAABB.min[1] = std::min(rootAABB.min[1], y);
+        rootAABB.min[2] = std::min(rootAABB.min[2], z);
+        rootAABB.max[0] = std::max(rootAABB.max[0], x);
+        rootAABB.max[1] = std::max(rootAABB.max[1], y);
+        rootAABB.max[2] = std::max(rootAABB.max[2], z);
+    }
+
+    // 2. Build Octree
+    std::vector<int32_t> allIndices(m_cloud.numPoints);
+    std::iota(allIndices.begin(), allIndices.end(), 0);
+
+    std::unique_ptr<OctreeNode> root = std::make_unique<OctreeNode>();
+    root->aabb = rootAABB;
+    root->pointIndices = std::move(allIndices);
+    root->depth = 0;
+
+    std::queue<OctreeNode*> queue;
+    queue.push(root.get());
+
+    while (!queue.empty()) {
+        OctreeNode* node = queue.front();
+        queue.pop();
+
+        // Check if we need to split
+        if (node->pointIndices.size() > (size_t)config.maxPointsPerTile) {
+            // Split into 8 children (Octree) or 4 children (Quadtree if ignoreZ)
+            int splitCount = config.ignoreZ ? 4 : 8;
+            for (int i = 0; i < splitCount; ++i) {
+                auto child = std::make_unique<OctreeNode>();
+                child->depth = node->depth + 1;
+                child->x = (node->x << 1) | ((i >> 0) & 1);
+                child->y = (node->y << 1) | ((i >> 1) & 1);
+                child->z = (node->z << 1) | ((i >> 2) & 1);
+                
+                // Calculate child AABB
+                for (int axis = 0; axis < 3; ++axis) {
+                    if (config.ignoreZ && axis == 2) {
+                        // Don't split Z axis
+                        child->aabb.min[axis] = node->aabb.min[axis];
+                        child->aabb.max[axis] = node->aabb.max[axis];
+                    } else {
+                        float center = node->aabb.center(axis);
+                        if ((i >> axis) & 1) {
+                            child->aabb.min[axis] = center;
+                            child->aabb.max[axis] = node->aabb.max[axis];
+                        } else {
+                            child->aabb.min[axis] = node->aabb.min[axis];
+                            child->aabb.max[axis] = center;
+                        }
+                    }
+                }
+                node->children.push_back(std::move(child));
+            }
+
+            // Distribute points
+            for (int32_t idx : node->pointIndices) {
+                float x = m_cloud.positions[idx * 3 + 0];
+                float y = m_cloud.positions[idx * 3 + 1];
+                float z = m_cloud.positions[idx * 3 + 2];
+
+                for (auto& child : node->children) {
+                    if (child->aabb.contains(x, y, z)) {
+                        child->pointIndices.push_back(idx);
+                        break;
+                    }
+                }
+            }
+
+            // Clear parent indices (we will refill them for LOD later)
+            node->pointIndices.clear();
+
+            // Enqueue non-empty children
+            for (auto& child : node->children) {
+                if (!child->pointIndices.empty()) {
+                    queue.push(child.get());
+                }
+            }
+        }
+    }
+
+    // 3. Generate LOD and Export (Bottom-Up)
+    
+    std::function<void(OctreeNode*)> generateLOD = [&](OctreeNode* node) {
+        if (node->children.empty()) {
+            // Leaf node: keep points as is.
+            node->geometricError = 0.0f; // Highest detail
+        } else {
+            // Inner node: process children first
+            for (auto& child : node->children) {
+                generateLOD(child.get());
+            }
+
+            // Additive LOD Generation:
+            // Move points from children to this node to fill up to maxPointsPerTile.
+            size_t totalChildPoints = 0;
+            for (auto& child : node->children) {
+                totalChildPoints += child->pointIndices.size();
+            }
+            
+            size_t targetCount = config.maxPointsPerTile;
+            bool takeAll = totalChildPoints <= targetCount;
+
+            for (auto& child : node->children) {
+                if (child->pointIndices.empty()) continue;
+
+                if (takeAll) {
+                    // Move all points from child to parent (Merge)
+                    node->pointIndices.insert(node->pointIndices.end(), child->pointIndices.begin(), child->pointIndices.end());
+                    child->pointIndices.clear();
+                } else {
+                    // Subsample: Copy a fraction of points to parent (REPLACE strategy)
+                    double fraction;
+                    if (config.lodStride > 1) {
+                        fraction = 1.0 / (double)config.lodStride;
+                    } else {
+                        fraction = (double)targetCount / (double)totalChildPoints;
+                    }
+                    
+                    size_t copyCount = (size_t)(child->pointIndices.size() * fraction);
+                    if (copyCount == 0 && targetCount > 0) copyCount = 1;
+                    
+                    // Multi-pass selection strategy to preserve different types of features
+                    struct PointMetric {
+                        int32_t index;
+                        float maxScale;
+                        float alpha;
+                        float luminance;
+                        float saturation;
+                        float random;
+                        bool selected;
+                    };
+
+                    std::vector<PointMetric> metrics;
+                    metrics.reserve(child->pointIndices.size());
+
+                    for (int32_t idx : child->pointIndices) {
+                        float maxLogScale = std::max({m_cloud.scales[idx * 3 + 0], m_cloud.scales[idx * 3 + 1], m_cloud.scales[idx * 3 + 2]});
+                        float maxScale = std::exp(maxLogScale);
+                        float alpha = 1.0f / (1.0f + std::exp(-m_cloud.alphas[idx]));
+
+                        float r = 0.5f + 0.28209f * m_cloud.colors[idx * 3 + 0];
+                        float g = 0.5f + 0.28209f * m_cloud.colors[idx * 3 + 1];
+                        float b = 0.5f + 0.28209f * m_cloud.colors[idx * 3 + 2];
+                        float lum = std::max(0.0f, (r + g + b) / 3.0f);
+                        
+                        float maxC = std::max({r, g, b});
+                        float minC = std::min({r, g, b});
+                        float sat = (maxC - minC) * alpha;
+
+                        float rnd = (float)(std::hash<int32_t>{}(idx) % 10000) / 10000.0f;
+                        metrics.push_back({idx, maxScale, alpha, lum, sat, rnd, false});
+                    }
+
+                    std::vector<int32_t> selectedIndices;
+                    selectedIndices.reserve(copyCount);
+
+                    #if 0
+
+                    std::sort(metrics.begin(), metrics.end(), [](const PointMetric& a, const PointMetric& b) {
+                        return a.random > b.random;
+                    });
+                    for (auto& m : metrics) {
+                        if (selectedIndices.size() >= copyCount) break;
+                        if (!m.selected) { m.selected = true; selectedIndices.push_back(m.index); }
+                    }
+
+                    #else
+
+                    // Define quotas for different priorities
+                    size_t targetP1 = (size_t)(copyCount * 0.10); // 15% Highlights
+                    size_t targetP2 = (size_t)(copyCount * 0.60); // 30% Structure (Cumulative 45%)
+                    size_t targetP3 = (size_t)(copyCount * 0.70); // 15% Saturation (Cumulative 60%)
+                    size_t targetP4 = (size_t)(copyCount * 0.85); // 15% Uniform (Cumulative 75%)
+                    size_t targetP5 = copyCount;                  // 25% Fill/Size (Cumulative 100%)
+
+                    // Pass 1: Highlights (Luminance * Alpha) - Preserves white chimneys, lights
+                    std::sort(metrics.begin(), metrics.end(), [](const PointMetric& a, const PointMetric& b) {
+                        return (a.luminance * a.alpha) > (b.luminance * b.alpha);
+                    });
+                    for (auto& m : metrics) {
+                        if (selectedIndices.size() >= targetP1) break;
+                        if (!m.selected) { m.selected = true; selectedIndices.push_back(m.index); }
+                    }
+
+                    // Pass 2: Structure (MaxScale * Alpha) - Preserves solid walls, roofs
+                    std::sort(metrics.begin(), metrics.end(), [](const PointMetric& a, const PointMetric& b) {
+                        return (a.maxScale * a.alpha) > (b.maxScale * b.alpha);
+                    });
+                    for (auto& m : metrics) {
+                        if (selectedIndices.size() >= targetP2) break;
+                        if (!m.selected) { m.selected = true; selectedIndices.push_back(m.index); }
+                    }
+
+                    // Pass 3: Saturation - Preserves colorful details (blue glasses, red signs)
+                    std::sort(metrics.begin(), metrics.end(), [](const PointMetric& a, const PointMetric& b) {
+                        return a.saturation > b.saturation;
+                    });
+                    for (auto& m : metrics) {
+                        if (selectedIndices.size() >= targetP3) break;
+                        if (!m.selected) { m.selected = true; selectedIndices.push_back(m.index); }
+                    }
+
+                    // Pass 4: Uniform - Preserves distribution (prevents holes)
+                    std::sort(metrics.begin(), metrics.end(), [](const PointMetric& a, const PointMetric& b) {
+                        return a.random > b.random;
+                    });
+                    for (auto& m : metrics) {
+                        if (selectedIndices.size() >= targetP4) break;
+                        if (!m.selected) { m.selected = true; selectedIndices.push_back(m.index); }
+                    }
+
+                    // Pass 5: Fill (MaxScale) - Preserves thin wires, large faint objects
+                    std::sort(metrics.begin(), metrics.end(), [](const PointMetric& a, const PointMetric& b) {
+                        return a.maxScale > b.maxScale;
+                    });
+                    for (auto& m : metrics) {
+                        if (selectedIndices.size() >= targetP5) break;
+                        if (!m.selected) { m.selected = true; selectedIndices.push_back(m.index); }
+                    }
+                    #endif
+
+                    node->pointIndices.insert(node->pointIndices.end(), selectedIndices.begin(), selectedIndices.end());
+                }
+            }
+
+            // Prune empty children (those that gave all their points to parent and have no children of their own)
+            node->children.erase(
+                std::remove_if(node->children.begin(), node->children.end(),
+                    [](const std::unique_ptr<OctreeNode>& child) {
+                        return child->pointIndices.empty() && child->children.empty();
+                    }),
+                node->children.end());
+
+            // Calculate geometric error based on bounds size
+            if (node->children.empty()) {
+                node->geometricError = 0.0f;
+            } else {
+                // Typical 3D Tiles calculation: Geometric error halves at each depth level.
+                // We use the root diagonal as the baseline to ensure monotonic decrease.
+                float rootDx = rootAABB.size(0);
+                float rootDy = rootAABB.size(1);
+                float rootDz = rootAABB.size(2);
+                float rootDiag = std::sqrt(rootDx * rootDx + rootDy * rootDy + rootDz * rootDz);
+                
+                // Error = RootDiagonal / 2^depth
+                node->geometricError = (rootDiag / std::pow(2.0f, node->depth)) * config.geometricErrorMultiplier;
+            }
+        }
+    };
+
+    generateLOD(root.get());
+
+    // Export Nodes (Top-Down)
+    std::function<void(OctreeNode*)> exportNodes = [&](OctreeNode* node) {
+        if (!node->pointIndices.empty()) {
+            spz::GaussianCloud subset = extractSubset(m_cloud, node->pointIndices);
+
+            // Calculate min/max for GLB header
+            float minPos[3] = {std::numeric_limits<float>::max(), std::numeric_limits<float>::max(), std::numeric_limits<float>::max()};
+            float maxPos[3] = {std::numeric_limits<float>::lowest(), std::numeric_limits<float>::lowest(), std::numeric_limits<float>::lowest()};
+            
+            for(size_t i=0; i<subset.numPoints; ++i) {
+                float x = subset.positions[i*3+0];
+                float y = subset.positions[i*3+1];
+                float z = subset.positions[i*3+2];
+                if(x < minPos[0]) minPos[0] = x;
+                if(y < minPos[1]) minPos[1] = y;
+                if(z < minPos[2]) minPos[2] = z;
+                if(x > maxPos[0]) maxPos[0] = x;
+                if(y > maxPos[1]) maxPos[1] = y;
+                if(z > maxPos[2]) maxPos[2] = z;
+            }
+            
+            // Pack options
+            spz::PackOptions packOpts;
+            packOpts.from = spz::CoordinateSystem::RUB;
+
+            std::vector<uint8_t> spzData;
+            if (spz::saveSpz(subset, packOpts, &spzData)) {
+                std::string filename = "tile_" + std::to_string(node->depth) + "_" +
+                                       std::to_string(node->x) + "_" +
+                                       std::to_string(node->y) + "_" +
+                                       std::to_string(node->z) +
+                                       (config.exportGlb ? ".glb" : ".spz");
+                node->filename = filename;
+                
+                std::string fullPath = (fs::path(config.outputDir) / filename).string();
+                
+                if (config.exportGlb) {
+                    writeGlbWithSpz(fullPath, spzData, subset.numPoints, subset.shDegree, minPos, maxPos);
+                } else {
+                    std::ofstream out(fullPath, std::ios::binary);
+                    out.write(reinterpret_cast<const char*>(spzData.data()), spzData.size());
+                }
+            }
+        }
+
+        for (auto& child : node->children) {
+            exportNodes(child.get());
+        }
+    };
+
+    exportNodes(root.get());
+
+    // 4. Generate tileset.json
+    std::ofstream tilesetOut(fs::path(config.outputDir) / "tileset.json");
+    tilesetOut << "{" << std::endl;
+    tilesetOut << "  \"asset\": { \"version\": \"1.1\" }," << std::endl;
+
+    float rootDx = root->aabb.size(0);
+    float rootDy = root->aabb.size(1);
+    float rootDz = root->aabb.size(2);
+    float rootDiagonal = std::sqrt(rootDx * rootDx + rootDy * rootDy + rootDz * rootDz);
+    tilesetOut << "  \"geometricError\": " << rootDiagonal * config.geometricErrorMultiplier << "," << std::endl;
+    tilesetOut << "  \"extensions\": {" << std::endl;
+    tilesetOut << "    \"3DTILES_content_gltf\": {" << std::endl;
+    tilesetOut << "      \"extensionsRequired\": [\"KHR_gaussian_splatting\", \"KHR_gaussian_splatting_compression_spz_2\"]," << std::endl;
+    tilesetOut << "      \"extensionsUsed\": [\"KHR_gaussian_splatting\", \"KHR_gaussian_splatting_compression_spz_2\"]" << std::endl;
+    tilesetOut << "    }" << std::endl;
+    tilesetOut << "  }," << std::endl;
+    tilesetOut << "  \"extensionsUsed\": [\"3DTILES_content_gltf\"]," << std::endl;
+    
+    tilesetOut << "  \"root\": {" << std::endl;
+    
+    if (config.useGeoreference) {
+        std::vector<double> m = computeTransform(config.latitude, config.longitude, config.altitude);
+        tilesetOut << "    \"transform\": [" << std::endl;
+        tilesetOut << "      " << m[0] << ", " << m[1] << ", " << m[2] << ", " << m[3] << "," << std::endl;
+        tilesetOut << "      " << m[4] << ", " << m[5] << ", " << m[6] << ", " << m[7] << "," << std::endl;
+        tilesetOut << "      " << m[8] << ", " << m[9] << ", " << m[10] << ", " << m[11] << "," << std::endl;
+        tilesetOut << "      " << m[12] << ", " << m[13] << ", " << m[14] << ", " << m[15] << std::endl;
+        tilesetOut << "    ]," << std::endl;
+    }
+
+    std::function<void(OctreeNode*)> writeTilesetNode = [&](OctreeNode* node) {
+        
+        // Bounding Volume
+        tilesetOut << "    \"boundingVolume\": { \"box\": [";
+        tilesetOut << node->aabb.center(0) << ", " << node->aabb.center(1) << ", " << node->aabb.center(2) << ", ";
+        tilesetOut << node->aabb.size(0)/2 << ", 0, 0, ";
+        tilesetOut << "0, " << node->aabb.size(1)/2 << ", 0, ";
+        tilesetOut << "0, 0, " << node->aabb.size(2)/2;
+        tilesetOut << "] }," << std::endl;
+
+        tilesetOut << "    \"geometricError\": " << node->geometricError << "," << std::endl;
+        tilesetOut << "    \"refine\": \"REPLACE\"";
+
+        if (!node->filename.empty()) {
+            tilesetOut << "," << std::endl;
+            tilesetOut << "    \"content\": { \"uri\": \"" << node->filename << "\" }";
+        }
+
+        // Children
+        if (!node->children.empty()) {
+            tilesetOut << "," << std::endl;
+            tilesetOut << "    \"children\": [" << std::endl;
+            bool first = true;
+            for (auto& child : node->children) {
+                if (!first) tilesetOut << "," << std::endl;
+                tilesetOut << "    {" << std::endl;
+                writeTilesetNode(child.get());
+                tilesetOut << "    }" << std::endl;
+                first = false;
+            }
+            tilesetOut << std::endl << "    ]" << std::endl;
+        }
+    };
+
+    writeTilesetNode(root.get());
+    tilesetOut << "  }" << std::endl;
+    tilesetOut << "}" << std::endl;
+}
+
+
+
+
+
+} // namespace tile3dgs

SplatTiler/SplatTiler.h

@@ -0,0 +1,44 @@
+#pragma once
+
+#include <string>
+#include <vector>
+#include <memory>
+#include "spz/load-spz.h"
+
+namespace tile3dgs {
+
+struct TileConfig {
+    int maxPointsPerTile = 65536;
+    std::string outputDir = "output_tiles";
+    // If true, wraps SPZ data in a GLB container. If false, exports raw .spz files.
+    bool exportGlb = true; 
+    bool ignoreZ = false;
+    // Subsampling rate for LOD generation (e.g., 2 means keep 1/2 points for parent)
+    int lodStride = 2; 
+
+    // Georeference options
+    bool useGeoreference = false;
+    double latitude = 0.0;
+    double longitude = 0.0;
+    double altitude = 0.0;
+
+    // Multiplier for geometric error calculation
+    float geometricErrorMultiplier = 1.0f;
+};
+
+class SplatTiler {
+public:
+    SplatTiler();
+    ~SplatTiler();
+
+    // Load a PLY file into memory
+    bool load(const std::string& plyFilename);
+
+    // Run the tiling and export process
+    void process(const TileConfig& config);
+
+private:
+    spz::GaussianCloud m_cloud;
+};
+
+} // namespace tile3dgs

SplatTiler/main.cpp

@@ -0,0 +1,166 @@
+#include <iostream>
+#include <string>
+#include <vector>
+#include <filesystem>
+
+#include "SplatTiler.h"
+
+void printUsage(const char* progName) {
+    std::cout << "Usage: " << progName << " [options] <input_ply>\n";
+    std::cout << "Options:\n";
+    std::cout << "  -o, --output <dir>       Output directory (default: output_tiles)\n";
+    std::cout << "  -m, --max-points <num>   Max points per tile (default: 65536)\n";
+    std::cout << "  -s, --stride <num>       LOD subsampling stride (default: 2)\n";
+    std::cout << "  --no-glb                 Export raw .spz files instead of .glb\n";
+    std::cout << "  --lat <val> --lon <val> --alt <val>  Georeference origin (WGS84)\n";
+    std::cout << "  --error-scale <val>      Geometric error multiplier (default: 1.0)\n";
+    std::cout << "  --ignore-z               Ignore Z axis when splitting (Quadtree)\n";
+    std::cout << "  -h, --help               Show this help message\n";
+}
+
+int main(int argc, char* argv[]) {
+    if (argc < 2) {
+        printUsage(argv[0]);
+        return 1;
+    }
+
+    tile3dgs::TileConfig config;
+    std::string inputPly;
+
+    for (int i = 1; i < argc; ++i) {
+        std::string arg = argv[i];
+
+        if (arg == "-h" || arg == "--help") {
+            printUsage(argv[0]);
+            return 0;
+        } else if (arg == "-o" || arg == "--output") {
+            if (i + 1 < argc) {
+                config.outputDir = argv[++i];
+            } else {
+                std::cerr << "Error: Missing argument for output directory\n";
+                return 1;
+            }
+        } else if (arg == "-m" || arg == "--max-points") {
+            if (i + 1 < argc) {
+                try {
+                    config.maxPointsPerTile = std::stoi(argv[++i]);
+                } catch (...) {
+                    std::cerr << "Error: Invalid number for max points\n";
+                    return 1;
+                }
+            } else {
+                std::cerr << "Error: Missing argument for max points\n";
+                return 1;
+            }
+        } else if (arg == "-s" || arg == "--stride") {
+            if (i + 1 < argc) {
+                try {
+                    config.lodStride = std::stoi(argv[++i]);
+                } catch (...) {
+                    std::cerr << "Error: Invalid number for stride\n";
+                    return 1;
+                }
+            } else {
+                std::cerr << "Error: Missing argument for stride\n";
+                return 1;
+            }
+        } else if (arg == "--no-glb") {
+            config.exportGlb = false;
+        } else if (arg == "--lat") {
+            if (i + 1 < argc) {
+                try {
+                    config.latitude = std::stod(argv[++i]);
+                    config.useGeoreference = true;
+                } catch (...) {
+                    std::cerr << "Error: Invalid latitude\n";
+                    return 1;
+                }
+            } else {
+                std::cerr << "Error: Missing argument for latitude\n";
+                return 1;
+            }
+        } else if (arg == "--lon") {
+            if (i + 1 < argc) {
+                try {
+                    config.longitude = std::stod(argv[++i]);
+                    config.useGeoreference = true;
+                } catch (...) {
+                    std::cerr << "Error: Invalid longitude\n";
+                    return 1;
+                }
+            } else {
+                std::cerr << "Error: Missing argument for longitude\n";
+                return 1;
+            }
+        } else if (arg == "--alt") {
+            if (i + 1 < argc) {
+                try {
+                    config.altitude = std::stod(argv[++i]);
+                } catch (...) {
+                    std::cerr << "Error: Invalid altitude\n";
+                    return 1;
+                }
+            } else {
+                std::cerr << "Error: Missing argument for altitude\n";
+                return 1;
+            }
+        } else if (arg == "--error-scale") {
+            if (i + 1 < argc) {
+                try {
+                    config.geometricErrorMultiplier = std::stof(argv[++i]);
+                } catch (...) {
+                    std::cerr << "Error: Invalid geometric error multiplier\n";
+                    return 1;
+                }
+            } else {
+                std::cerr << "Error: Missing argument for error scale\n";
+                return 1;
+            }
+        } else if (arg == "--ignore-z") {
+            config.ignoreZ = true;
+        } else if (arg[0] == '-') {
+            std::cerr << "Unknown option: " << arg << "\n";
+            printUsage(argv[0]);
+            return 1;
+        } else {
+            inputPly = arg;
+        }
+    }
+
+    if (inputPly.empty()) {
+        std::cerr << "Error: No input PLY file specified.\n";
+        printUsage(argv[0]);
+        return 1;
+    }
+
+    if (!std::filesystem::exists(inputPly)) {
+        std::cerr << "Error: Input file does not exist: " << inputPly << "\n";
+        return 1;
+    }
+
+    std::cout << "Loading " << inputPly << "...\n";
+    tile3dgs::SplatTiler tiler;
+    if (!tiler.load(inputPly)) {
+        std::cerr << "Failed to load PLY file (or file is empty).\n";
+        return 1;
+    }
+
+    std::cout << "Processing tiles...\n";
+    std::cout << "  Output Dir: " << config.outputDir << "\n";
+    std::cout << "  Max Points: " << config.maxPointsPerTile << "\n";
+    std::cout << "  LOD Stride: " << config.lodStride << "\n";
+    std::cout << "  Format: " << (config.exportGlb ? "GLB (with embedded SPZ)" : "SPZ") << "\n";
+    if (config.useGeoreference) {
+        std::cout << "  Georeference: " << config.latitude << ", " << config.longitude << ", " << config.altitude << "\n";
+    }
+    std::cout << "  Error Scale: " << config.geometricErrorMultiplier << "\n";
+    if (config.ignoreZ) {
+        std::cout << "  Ignore Z: true (Quadtree mode)\n";
+    }
+
+    tiler.process(config);
+
+    std::cout << "Done.\n";
+
+    return 0;
+}

SplatTiler/spz/load-spz.cc

@@ -0,0 +1,936 @@
+#include "load-spz.h"
+
+#include <zlib.h>
+
+#ifdef ANDROID
+#include <android/log.h>
+#endif
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <fstream>
+#include <iostream>
+#include <sstream>
+#include <unordered_map>
+#include <vector>
+
+namespace spz {
+
+namespace {
+
+#ifdef ANDROID
+static constexpr char LOG_TAG[] = "SPZ";
+template <class... Args>
+static void SpzLog(const char *fmt, Args &&...args) {
+  __android_log_print(ANDROID_LOG_INFO, LOG_TAG, fmt, std::forward<Args>(args)...);
+}
+#else
+template <class... Args>
+static void SpzLog(const char *fmt, Args &&...args) {
+  printf(fmt, std::forward<Args>(args)...);
+  printf("\n");
+  fflush(stdout);
+}
+#endif  // ANDROID
+
+template <class... Args>
+static void SpzLog(const char *fmt) {
+  SpzLog("%s", fmt);
+}
+
+// Scale factor for DC color components. To convert to RGB, we should multiply by 0.282, but it can
+// be useful to represent base colors that are out of range if the higher spherical harmonics bands
+// bring them back into range so we multiply by a smaller value.
+constexpr float colorScale = 0.15f;
+constexpr float sqrt1_2 = (float)0.707106781186547524401; // 1/sqrt(2)
+
+int32_t degreeForDim(int32_t dim) {
+  if (dim < 3)
+    return 0;
+  if (dim < 8)
+    return 1;
+  if (dim < 15)
+    return 2;
+  return 3;
+}
+
+int32_t dimForDegree(int32_t degree) {
+  switch (degree) {
+    case 0:
+      return 0;
+    case 1:
+      return 3;
+    case 2:
+      return 8;
+    case 3:
+      return 15;
+    default:
+      SpzLog("[SPZ: ERROR] Unsupported SH degree: %d\n", degree);
+      return 0;
+  }
+}
+
+uint8_t toUint8(float x) { return static_cast<uint8_t>(std::clamp(std::round(x), 0.0f, 255.0f)); }
+
+// Quantizes to 8 bits, the round to nearest bucket center. 0 always maps to a bucket center.
+uint8_t quantizeSH(float x, int32_t bucketSize) {
+  int32_t q = static_cast<int>(std::round(x * 128.0f) + 128.0f);
+  q = (q + bucketSize / 2) / bucketSize * bucketSize;
+  return static_cast<uint8_t>(std::clamp(q, 0, 255));
+}
+
+float unquantizeSH(uint8_t x) { return (static_cast<float>(x) - 128.0f) / 128.0f; }
+
+float sigmoid(float x) { return 1 / (1 + std::exp(-x)); }
+
+float invSigmoid(float x) { return std::log(x / (1.0f - x)); }
+
+template <typename T>
+size_t countBytes(std::vector<T> vec) {
+  return vec.size() * sizeof(vec[0]);
+}
+
+#define CHECK(x)                                                              \
+  {                                                                           \
+    if (!(x)) {                                                               \
+      SpzLog("[SPZ: ERROR] Check failed: %s:%d: %s", __FILE__, __LINE__, #x); \
+      return false;                                                           \
+    }                                                                         \
+  }
+
+#define CHECK_GE(x, y) CHECK((x) >= (y))
+#define CHECK_LE(x, y) CHECK((x) <= (y))
+#define CHECK_EQ(x, y) CHECK((x) == (y))
+
+bool checkSizes(const GaussianCloud &g) {
+  CHECK_GE(g.numPoints, 0);
+  CHECK_GE(g.shDegree, 0);
+  CHECK_LE(g.shDegree, 3);
+  CHECK_EQ(g.positions.size(), g.numPoints * 3);
+  CHECK_EQ(g.scales.size(), g.numPoints * 3);
+  CHECK_EQ(g.rotations.size(), g.numPoints * 4);
+  CHECK_EQ(g.alphas.size(), g.numPoints);
+  CHECK_EQ(g.colors.size(), g.numPoints * 3);
+  CHECK_EQ(g.sh.size(), g.numPoints * dimForDegree(g.shDegree) * 3);
+  return true;
+}
+
+bool checkSizes(const PackedGaussians &packed, int32_t numPoints, int32_t shDim, bool usesFloat16) {
+  CHECK_EQ(packed.positions.size(), numPoints * 3 * (usesFloat16 ? 2 : 3));
+  CHECK_EQ(packed.scales.size(), numPoints * 3);
+  CHECK_EQ(packed.rotations.size(), numPoints * (packed.usesQuaternionSmallestThree ? 4 : 3));
+  CHECK_EQ(packed.alphas.size(), numPoints);
+  CHECK_EQ(packed.colors.size(), numPoints * 3);
+  CHECK_EQ(packed.sh.size(), numPoints * shDim * 3);
+  return true;
+}
+
+constexpr uint8_t FlagAntialiased = 0x1;
+
+struct PackedGaussiansHeader {
+  uint32_t magic = 0x5053474e;  // NGSP = Niantic gaussian splat
+  uint32_t version = 3;
+  uint32_t numPoints = 0;
+  uint8_t shDegree = 0;
+  uint8_t fractionalBits = 0;
+  uint8_t flags = 0;
+  uint8_t reserved = 0;
+};
+
+bool decompressGzippedImpl(
+  const uint8_t *compressed, size_t size, int32_t windowSize, std::vector<uint8_t> *out) {
+  std::vector<uint8_t> buffer(8192);
+  z_stream stream = {};
+  stream.next_in = const_cast<Bytef *>(compressed);
+  stream.avail_in = size;
+  if (inflateInit2(&stream, windowSize) != Z_OK) {
+    return false;
+  }
+  out->clear();
+  bool success = false;
+  while (true) {
+    stream.next_out = buffer.data();
+    stream.avail_out = buffer.size();
+    int32_t res = inflate(&stream, Z_NO_FLUSH);
+    if (res != Z_OK && res != Z_STREAM_END) {
+      break;
+    }
+    out->insert(out->end(), buffer.data(), buffer.data() + buffer.size() - stream.avail_out);
+    if (res == Z_STREAM_END) {
+      success = true;
+      break;
+    }
+  }
+  inflateEnd(&stream);
+  return success;
+}
+
+bool decompressGzipped(const uint8_t *compressed, size_t size, std::vector<uint8_t> *out) {
+  // Here 16 means enable automatic gzip header detection; consider switching this to 32 to enable
+  // both automated gzip and zlib header detection.
+  return decompressGzippedImpl(compressed, size, 16 | MAX_WBITS, out);
+}
+
+bool decompressGzipped(const uint8_t *compressed, size_t size, std::string *out) {
+  std::vector<uint8_t> buffer;
+  if (!decompressGzipped(compressed, size, &buffer)) {
+    return false;
+  }
+  out->assign(reinterpret_cast<const char *>(buffer.data()), buffer.size());
+  return true;
+}
+
+}  // namespace
+
+bool compressGzipped(const uint8_t *data, size_t size, std::vector<uint8_t> *out) {
+  std::vector<uint8_t> buffer(8192);
+  z_stream stream = {};
+  if (
+    deflateInit2(&stream, Z_DEFAULT_COMPRESSION, Z_DEFLATED, 16 + MAX_WBITS, 9, Z_DEFAULT_STRATEGY)
+    != Z_OK) {
+    return false;
+  }
+  out->clear();
+  out->reserve(size / 4);
+  stream.next_in = const_cast<Bytef *>(reinterpret_cast<const Bytef *>(data));
+  stream.avail_in = size;
+  bool success = false;
+  while (true) {
+    stream.next_out = buffer.data();
+    stream.avail_out = buffer.size();
+    int32_t res = deflate(&stream, Z_FINISH);
+    if (res != Z_OK && res != Z_STREAM_END) {
+      break;
+    }
+    out->insert(out->end(), buffer.data(), buffer.data() + buffer.size() - stream.avail_out);
+    if (res == Z_STREAM_END) {
+      success = true;
+      break;
+    }
+  }
+  deflateEnd(&stream);
+  return success;
+}
+
+void packQuaternionSmallestThree(uint8_t r[4], const float rotation[4], const CoordinateConverter& c) {
+  // Normalize the quaternion
+  Quat4f q = normalized(quat4f(&rotation[0]));
+  q[0] *= c.flipQ[0];
+  q[1] *= c.flipQ[1];
+  q[2] *= c.flipQ[2];
+
+  // Find largest component
+  unsigned iLargest = 0;
+  for (unsigned i = 1; i < 4; ++i)
+  {
+    if (std::abs(q[i]) > std::abs(q[iLargest]))
+    {
+      iLargest = i;
+    }
+  }
+
+  // since -q represents the same rotation as q, transform the quaternion so the largest element
+  // is positive. This avoids having to send its sign bit.
+  unsigned negate = q[iLargest] < 0;
+
+  // Do compression using sign bit and 9-bit precision per element.
+  uint32_t comp = iLargest;
+  for (unsigned i = 0; i < 4; ++i)
+  {
+      if (i != iLargest)
+      {
+          uint32_t negbit = (q[i] < 0) ^ negate;
+          uint32_t mag =
+              (uint32_t)(float((1u << 9u) - 1u) * (std::fabs(q[i]) / sqrt1_2) + 0.5f);
+          comp = (comp << 10u) | (negbit << 9u) | mag;
+      }
+  }
+
+  // Ensure little-endianness on all platforms
+  r[0] = comp & 0xff;
+  r[1] = (comp >> 8) & 0xff;
+  r[2] = (comp >> 16) & 0xff;
+  r[3] = (comp >> 24) & 0xff;
+}
+
+PackedGaussians packGaussians(const GaussianCloud &g, const PackOptions &o) {
+  if (!checkSizes(g)) {
+    return {};
+  }
+  const int32_t numPoints = g.numPoints;
+  const int32_t shDim = dimForDegree(g.shDegree);
+  CoordinateConverter c = coordinateConverter(o.from, CoordinateSystem::RUB);
+
+  // Use 12 bits for the fractional part of coordinates (~0.25 millimeter resolution). In the future
+  // we can use different values on a per-splat basis and still be compatible with the decoder.
+  PackedGaussians packed;
+  packed.numPoints = g.numPoints;
+  packed.shDegree = g.shDegree;
+  packed.fractionalBits = 12;
+  packed.antialiased = g.antialiased;
+  packed.usesQuaternionSmallestThree = true;
+  packed.positions.resize(numPoints * 3 * 3);
+  packed.scales.resize(numPoints * 3);
+  packed.rotations.resize(numPoints * 4);
+  packed.alphas.resize(numPoints);
+  packed.colors.resize(numPoints * 3);
+  packed.sh.resize(numPoints * shDim * 3);
+
+  // Store coordinates as 24-bit fixed point values.
+  const float scale = (1 << packed.fractionalBits);
+  for (size_t i = 0; i < numPoints * 3; i++) {
+    const int32_t fixed32 =
+      static_cast<int32_t>(std::round(c.flipP[i % 3] * g.positions[i] * scale));
+    packed.positions[i * 3 + 0] = fixed32 & 0xff;
+    packed.positions[i * 3 + 1] = (fixed32 >> 8) & 0xff;
+    packed.positions[i * 3 + 2] = (fixed32 >> 16) & 0xff;
+  }
+
+  for (size_t i = 0; i < numPoints * 3; i++) {
+    packed.scales[i] = toUint8((g.scales[i] + 10.0f) * 16.0f);
+  }
+
+  for (size_t i = 0; i < numPoints; i++)
+  {
+    packQuaternionSmallestThree(&packed.rotations[4 * i], &g.rotations[4 * i], c);
+  }
+
+  for (size_t i = 0; i < numPoints; i++) {
+    // Apply sigmoid activation to alpha
+    packed.alphas[i] = toUint8(sigmoid(g.alphas[i]) * 255.0f);
+  }
+
+  for (size_t i = 0; i < numPoints * 3; i++) {
+    // Convert SH DC component to wide RGB (allowing values that are a bit above 1 and below 0).
+    packed.colors[i] = toUint8(g.colors[i] * (colorScale * 255.0f) + (0.5f * 255.0f));
+  }
+
+  if (g.shDegree > 0) {
+    // Spherical harmonics quantization parameters. The data format uses 8 bits per coefficient, but
+    // when packing, we can quantize to fewer bits for better compression.
+    constexpr int32_t sh1Bits = 5;
+    constexpr int32_t shRestBits = 4;
+    const int32_t shPerPoint = dimForDegree(g.shDegree) * 3;
+    for (size_t i = 0; i < numPoints * shPerPoint; i += shPerPoint) {
+      size_t j = 0, k = 0;
+      for (; j < 9; j += 3, k++) {  // There are 9 (3 * 3) coefficients for degree 1
+        packed.sh[i + j + 0] = quantizeSH(c.flipSh[k] * g.sh[i + j + 0], 1 << (8 - sh1Bits));
+        packed.sh[i + j + 1] = quantizeSH(c.flipSh[k] * g.sh[i + j + 1], 1 << (8 - sh1Bits));
+        packed.sh[i + j + 2] = quantizeSH(c.flipSh[k] * g.sh[i + j + 2], 1 << (8 - sh1Bits));
+      }
+      for (; j < shPerPoint; j += 3, k++) {
+        packed.sh[i + j + 0] = quantizeSH(c.flipSh[k] * g.sh[i + j + 0], 1 << (8 - shRestBits));
+        packed.sh[i + j + 1] = quantizeSH(c.flipSh[k] * g.sh[i + j + 1], 1 << (8 - shRestBits));
+        packed.sh[i + j + 2] = quantizeSH(c.flipSh[k] * g.sh[i + j + 2], 1 << (8 - shRestBits));
+      }
+    }
+  }
+
+  return packed;
+}
+
+void unpackQuaternionFirstThree(float rotation[4], const uint8_t r[3], const CoordinateConverter& c = CoordinateConverter())
+{
+  Vec3f xyz = times(
+    plus(
+      times(
+        Vec3f{ static_cast<float>(r[0]), static_cast<float>(r[1]), static_cast<float>(r[2]) },
+        1.0f / 127.5f),
+      Vec3f{ -1, -1, -1 }),
+    c.flipQ);
+  std::copy(xyz.data(), xyz.data() + 3, &rotation[0]);
+  // Compute the real component - we know the quaternion is normalized and w is non-negative
+  rotation[3] = std::sqrt(std::max(0.0f, 1.0f - squaredNorm(xyz)));
+}
+
+void unpackQuaternionSmallestThree(float rotation[4], const uint8_t r[4], const CoordinateConverter& c = CoordinateConverter())
+{
+  uint32_t comp =
+    r[0] +
+    (r[1] << 8) +
+    (r[2] << 16) +
+    (r[3] << 24);
+
+  constexpr uint32_t c_mask = (1u << 9u) - 1u;
+
+  const int i_largest = comp >> 30;
+  float sum_squares = 0;
+  // [unroll]
+  for (int i = 3; i >= 0; --i)
+  {
+    if (i != i_largest)
+    {
+      uint32_t mag    = comp & c_mask;
+      uint32_t negbit = (comp >> 9u) & 0x1u;
+      comp            = comp >> 10u;
+      rotation[i]     = sqrt1_2 * ((float)mag) / float(c_mask);
+      if (negbit == 1)
+      {
+        rotation[i] = -rotation[i];
+      }
+      sum_squares += rotation[i] * rotation[i];
+    }
+  }
+  rotation[i_largest] = sqrt(1.0f - sum_squares);
+
+  for (int i = 0; i < 3; i++)
+  {
+    rotation[i] *= c.flipQ[i];
+  }
+}
+
+UnpackedGaussian PackedGaussian::unpack(
+  bool usesFloat16, bool usesQuaternionSmallestThree, int32_t fractionalBits, const CoordinateConverter &c) const {
+  UnpackedGaussian result;
+  if (usesFloat16) {
+    // Decode legacy float16 format. We can remove this at some point as it was never released.
+    const auto *halfData = reinterpret_cast<const Half *>(position.data());
+    for (size_t i = 0; i < 3; i++) {
+      result.position[i] = c.flipP[i] * halfToFloat(halfData[i]);
+    }
+  } else {
+    // Decode 24-bit fixed point coordinates
+    float scale = 1.0 / (1 << fractionalBits);
+    for (size_t i = 0; i < 3; i++) {
+      int32_t fixed32 = position[i * 3 + 0];
+      fixed32 |= position[i * 3 + 1] << 8;
+      fixed32 |= position[i * 3 + 2] << 16;
+      fixed32 |= (fixed32 & 0x800000) ? 0xff000000 : 0;  // sign extension
+      result.position[i] = c.flipP[i] * static_cast<float>(fixed32) * scale;
+    }
+  }
+
+  for (size_t i = 0; i < 3; i++) {
+    result.scale[i] = (scale[i] / 16.0f - 10.0f);
+  }
+
+  if (usesQuaternionSmallestThree)
+  {
+      unpackQuaternionSmallestThree(&result.rotation[0], &rotation[0], c);
+  }
+  else
+  {
+      unpackQuaternionFirstThree(&result.rotation[0], &rotation[0], c);
+  }
+
+  result.alpha = invSigmoid(alpha / 255.0f);
+
+  for (size_t i = 0; i < 3; i++) {
+    result.color[i] = ((color[i] / 255.0f) - 0.5f) / colorScale;
+  }
+
+  for (size_t i = 0; i < 15; i++) {
+    result.shR[i] = c.flipSh[i] * unquantizeSH(shR[i]);
+    result.shG[i] = c.flipSh[i] * unquantizeSH(shG[i]);
+    result.shB[i] = c.flipSh[i] * unquantizeSH(shB[i]);
+  }
+
+  return result;
+}
+
+PackedGaussian PackedGaussians::at(int32_t i) const {
+  PackedGaussian result;
+  int32_t positionBytes = usesFloat16() ? 6 : 9;
+  int32_t start3 = i * 3;
+  const auto *p = &positions[i * positionBytes];
+  std::copy(p, p + positionBytes, result.position.data());
+  std::copy(&scales[start3], &scales[start3] + 3, result.scale.data());
+  int32_t rotationBytes = usesQuaternionSmallestThree ? 4 : 3;
+  const auto& r = &rotations[i * rotationBytes];
+  std::copy(r, r + rotationBytes, result.rotation.data());
+  std::copy(&colors[start3], &colors[start3] + 3, result.color.data());
+  result.alpha = alphas[i];
+
+  int32_t shDim = dimForDegree(shDegree);
+  const auto *sh = &this->sh[i * shDim * 3];
+  for (int32_t j = 0; j < shDim; ++j, sh += 3) {
+    result.shR[j] = sh[0];
+    result.shG[j] = sh[1];
+    result.shB[j] = sh[2];
+  }
+  for (int32_t j = shDim; j < 15; ++j) {
+    result.shR[j] = 128;
+    result.shG[j] = 128;
+    result.shB[j] = 128;
+  }
+
+  return result;
+}
+
+UnpackedGaussian PackedGaussians::unpack(int32_t i, const CoordinateConverter &c) const {
+  return at(i).unpack(usesFloat16(), usesQuaternionSmallestThree, fractionalBits, c);
+}
+
+bool PackedGaussians::usesFloat16() const { return positions.size() == numPoints * 3 * 2; }
+
+GaussianCloud unpackGaussians(const PackedGaussians &packed, const UnpackOptions &o) {
+  const int32_t numPoints = packed.numPoints;
+  const int32_t shDim = dimForDegree(packed.shDegree);
+  const bool usesFloat16 = packed.usesFloat16();
+  const bool usesQuaternionSmallestThree = packed.usesQuaternionSmallestThree;
+  if (!checkSizes(packed, numPoints, shDim, usesFloat16)) {
+    return {};
+  }
+
+  GaussianCloud result;
+  result.numPoints = packed.numPoints;
+  result.shDegree = packed.shDegree;
+  result.antialiased = packed.antialiased;
+  result.positions.resize(numPoints * 3);
+  result.scales.resize(numPoints * 3);
+  result.rotations.resize(numPoints * 4);
+  result.alphas.resize(numPoints);
+  result.colors.resize(numPoints * 3);
+  result.sh.resize(numPoints * shDim * 3);
+
+  if (usesFloat16) {
+    // Decode legacy float16 format. We can remove this at some point as it was never released.
+    const auto *halfData = reinterpret_cast<const Half *>(packed.positions.data());
+    for (size_t i = 0; i < numPoints * 3; i++) {
+      result.positions[i] = halfToFloat(halfData[i]);
+    }
+  } else {
+    // Decode 24-bit fixed point coordinates
+    float scale = 1.0 / (1 << packed.fractionalBits);
+    for (size_t i = 0; i < numPoints * 3; i++) {
+      int32_t fixed32 = packed.positions[i * 3 + 0];
+      fixed32 |= packed.positions[i * 3 + 1] << 8;
+      fixed32 |= packed.positions[i * 3 + 2] << 16;
+      fixed32 |= (fixed32 & 0x800000) ? 0xff000000 : 0;  // sign extension
+      result.positions[i] = static_cast<float>(fixed32) * scale;
+    }
+  }
+
+  for (size_t i = 0; i < numPoints * 3; i++) {
+    result.scales[i] = packed.scales[i] / 16.0f - 10.0f;
+  }
+
+  for (size_t i = 0; i < numPoints; i++) {
+    if (usesQuaternionSmallestThree) {
+      unpackQuaternionSmallestThree(&result.rotations[4 * i], &packed.rotations[4 * i]);
+    } else {
+      unpackQuaternionFirstThree(&result.rotations[4 * i], &packed.rotations[3 * i]);
+    }
+  }
+
+  for (size_t i = 0; i < numPoints; i++) {
+    result.alphas[i] = invSigmoid(packed.alphas[i] / 255.0f);
+  }
+
+  for (size_t i = 0; i < numPoints * 3; i++) {
+    result.colors[i] = ((packed.colors[i] / 255.0f) - 0.5f) / colorScale;
+  }
+
+  for (size_t i = 0; i < packed.sh.size(); i++) {
+    result.sh[i] = unquantizeSH(packed.sh[i]);
+  }
+
+  result.convertCoordinates(CoordinateSystem::RUB, o.to);
+  return result;
+}
+
+void serializePackedGaussians(const PackedGaussians &packed, std::ostream *out) {
+  PackedGaussiansHeader header;
+  header.numPoints = static_cast<uint32_t>(packed.numPoints);
+  header.shDegree = static_cast<uint8_t>(packed.shDegree);
+  header.fractionalBits = static_cast<uint8_t>(packed.fractionalBits);
+  header.flags = static_cast<uint8_t>(packed.antialiased ? FlagAntialiased : 0);
+  out->write(reinterpret_cast<const char *>(&header), sizeof(header));
+  out->write(reinterpret_cast<const char *>(packed.positions.data()), countBytes(packed.positions));
+  out->write(reinterpret_cast<const char *>(packed.alphas.data()), countBytes(packed.alphas));
+  out->write(reinterpret_cast<const char *>(packed.colors.data()), countBytes(packed.colors));
+  out->write(reinterpret_cast<const char *>(packed.scales.data()), countBytes(packed.scales));
+  out->write(reinterpret_cast<const char *>(packed.rotations.data()), countBytes(packed.rotations));
+  out->write(reinterpret_cast<const char *>(packed.sh.data()), countBytes(packed.sh));
+}
+
+PackedGaussians deserializePackedGaussians(std::istream &in) {
+  constexpr int32_t maxPointsToRead = 10000000;
+
+  PackedGaussiansHeader header;
+  in.read(reinterpret_cast<char *>(&header), sizeof(header));
+  if (!in || header.magic != PackedGaussiansHeader().magic) {
+    SpzLog("[SPZ ERROR] deserializePackedGaussians: header not found");
+    return {};
+  }
+  if (header.version < 1 || header.version > 3) {
+    SpzLog("[SPZ ERROR] deserializePackedGaussians: version not supported: %d", header.version);
+    return {};
+  }
+  if (header.numPoints > maxPointsToRead) {
+    SpzLog("[SPZ ERROR] deserializePackedGaussians: Too many points: %d", header.numPoints);
+    return {};
+  }
+  if (header.shDegree > 3) {
+    SpzLog("[SPZ ERROR] deserializePackedGaussians: Unsupported SH degree: %d", header.shDegree);
+    return {};
+  }
+  const int32_t numPoints = header.numPoints;
+  const int32_t shDim = dimForDegree(header.shDegree);
+  const bool usesFloat16 = header.version == 1;
+  const bool usesQuaternionSmallestThree = header.version >= 3;
+  PackedGaussians result;
+  result.numPoints = numPoints;
+  result.shDegree = header.shDegree;
+  result.fractionalBits = header.fractionalBits;
+  result.antialiased = (header.flags & FlagAntialiased) != 0;
+  result.positions.resize(numPoints * 3 * (usesFloat16 ? 2 : 3));
+  result.scales.resize(numPoints * 3);
+  result.usesQuaternionSmallestThree = usesQuaternionSmallestThree;
+  result.rotations.resize(numPoints * (usesQuaternionSmallestThree ? 4 : 3));  
+  result.alphas.resize(numPoints);
+  result.colors.resize(numPoints * 3);
+  result.sh.resize(numPoints * shDim * 3);
+  in.read(reinterpret_cast<char *>(result.positions.data()), countBytes(result.positions));
+  in.read(reinterpret_cast<char *>(result.alphas.data()), countBytes(result.alphas));
+  in.read(reinterpret_cast<char *>(result.colors.data()), countBytes(result.colors));
+  in.read(reinterpret_cast<char *>(result.scales.data()), countBytes(result.scales));
+  in.read(reinterpret_cast<char *>(result.rotations.data()), countBytes(result.rotations));
+  in.read(reinterpret_cast<char *>(result.sh.data()), countBytes(result.sh));
+  if (!in) {
+    SpzLog("[SPZ ERROR] deserializePackedGaussians: read error");
+    return {};
+  }
+  return result;
+}
+
+bool saveSpz(const GaussianCloud &g, const PackOptions &o, std::vector<uint8_t> *out) {
+  std::string data;
+  {
+    PackedGaussians packed = packGaussians(g, o);
+    std::stringstream ss;
+    serializePackedGaussians(packed, &ss);
+    data = ss.str();
+  }
+  return compressGzipped(reinterpret_cast<const uint8_t *>(data.data()), data.size(), out);
+}
+
+PackedGaussians loadSpzPacked(const uint8_t *data, int32_t size) {
+  std::string decompressed;
+  if (!decompressGzipped(data, size, &decompressed))
+    return {};
+  std::stringstream stream(std::move(decompressed));
+  return deserializePackedGaussians(stream);
+}
+
+PackedGaussians loadSpzPacked(const std::vector<uint8_t> &data) {
+  return loadSpzPacked(data.data(), static_cast<int>(data.size()));
+}
+
+PackedGaussians loadSpzPacked(const std::string &filename) {
+  std::ifstream in(filename, std::ios::binary | std::ios::ate);
+  if (!in.good())
+    return {};
+  std::vector<uint8_t> data(in.tellg());
+  in.seekg(0, std::ios::beg);
+  in.read(reinterpret_cast<char *>(data.data()), data.size());
+  if (!in.good()) {
+    return {};
+  }
+  return loadSpzPacked(data);
+}
+
+GaussianCloud loadSpz(const std::vector<uint8_t> &data, const UnpackOptions &o) {
+  return unpackGaussians(loadSpzPacked(data), o);
+}
+
+GaussianCloud loadSpz(const uint8_t *data, int32_t size, const UnpackOptions &o) {
+  return unpackGaussians(loadSpzPacked(data, size), o);
+}
+
+bool saveSpz(const GaussianCloud &g, const PackOptions &o, const std::string &filename) {
+  std::vector<uint8_t> data;
+  if (!saveSpz(g, o, &data)) {
+    return false;
+  }
+  std::ofstream out(filename, std::ios::binary | std::ios::out);
+  out.write(reinterpret_cast<const char *>(data.data()), data.size());
+  out.close();
+  return out.good();
+}
+
+GaussianCloud loadSpz(const std::string &filename, const UnpackOptions &o) {
+  std::ifstream in(filename, std::ios::binary | std::ios::ate);
+  if (!in.good()) {
+    SpzLog("[SPZ ERROR] Unable to open: %s", filename.c_str());
+    return {};
+  }
+  std::vector<uint8_t> data(in.tellg());
+  in.seekg(0, std::ios::beg);
+  in.read(reinterpret_cast<char *>(data.data()), data.size());
+  in.close();
+  if (!in.good()) {
+    SpzLog("[SPZ ERROR] Unable to load data from: %s", filename.c_str());
+    return {};
+  }
+  return loadSpz(data, o);
+}
+
+bool getNextHeaderLine(std::ifstream &in, std::string &line) {
+  while (std::getline(in, line)) {
+    // Find the first non-whitespace character
+    size_t start = line.find_first_not_of(" \t\n\r\f\v");
+    // If line is empty or whitespace-only, skip it and continue reading.
+    if (std::string::npos == start) {
+      continue;
+    }
+    // Trim leading whitespace and check for 'comment'
+    std::string trimmed_line = line.substr(start);
+    if (trimmed_line.rfind("comment", 0) == 0) {
+      continue; // Skip comment line
+    }
+    // Found a valid non-comment, non-empty line
+    line = trimmed_line; // Update the reference string with the trimmed line
+    return true;
+  }
+  // Failed to read a line (EOF or error)
+  return false;
+}
+
+GaussianCloud loadSplatFromPly(const std::string &filename, const UnpackOptions &o) {
+  SpzLog("[SPZ] Loading: %s", filename.c_str());
+  std::ifstream in(filename, std::ios::binary);
+  if (!in.good()) {
+    SpzLog("[SPZ ERROR] Unable to open: %s", filename.c_str());
+    in.close();
+    return {};
+  }
+  std::string line;
+  std::getline(in, line);
+  if (line != "ply") {
+    SpzLog("[SPZ ERROR] %s: not a .ply file", filename.c_str());
+    in.close();
+    return {};
+  }
+  if (!getNextHeaderLine(in, line) || line != "format binary_little_endian 1.0") {
+    SpzLog("[SPZ ERROR] %s: unsupported .ply format", filename.c_str());
+    in.close();
+    return {};
+  }
+  if (!getNextHeaderLine(in, line) || line.find("element vertex ") != 0) {
+    SpzLog("[SPZ ERROR] %s: missing vertex count", filename.c_str());
+    in.close();
+    return {};
+  }
+  int32_t numPoints = std::stoi(line.substr(std::strlen("element vertex ")));
+  if (numPoints <= 0 || numPoints > 10 * 1024 * 1024) {
+    SpzLog("[SPZ ERROR] %s: invalid vertex count: %d", filename.c_str(), numPoints);
+    in.close();
+    return {};
+  }
+
+  SpzLog("[SPZ] Loading %d points", numPoints);
+  std::unordered_map<std::string, int> fields;  // name -> index
+  for (int32_t i = 0;; i++) {
+    if (!getNextHeaderLine(in, line)) {
+      SpzLog("[SPZ ERROR] %s: unexpected EOF while reading header properties.", filename.c_str());
+      in.close();
+      return {};
+    }
+    if (line == "end_header")
+      break;
+
+    if (line.find("property float ") != 0) {
+      SpzLog("[SPZ ERROR] %s: unsupported property data type: %s", filename.c_str(), line.c_str());
+      in.close();
+      return {};
+    }
+    std::string name = line.substr(std::strlen("property float "));
+    fields[name] = i;
+  }
+
+  // Returns the index for a given field name, ensuring the name exists.
+  const auto index = [&fields](const std::string &name) {
+    const auto &itr = fields.find(name);
+    if (itr == fields.end()) {
+      SpzLog("[SPZ ERROR] Missing field: %s", name.c_str());
+      return -1;
+    }
+    return itr->second;
+  };
+
+  const std::vector<int> positionIdx = {index("x"), index("y"), index("z")};
+  const std::vector<int> scaleIdx = {index("scale_0"), index("scale_1"), index("scale_2")};
+  const std::vector<int> rotIdx = {index("rot_1"), index("rot_2"), index("rot_3"), index("rot_0")};
+  const std::vector<int> alphaIdx = {index("opacity")};
+  const std::vector<int> colorIdx = {index("f_dc_0"), index("f_dc_1"), index("f_dc_2")};
+
+  // Check that only valid indices were returned.
+  for (auto idx : positionIdx) {
+    if (idx < 0) {
+      in.close();
+      return {};
+    }
+  }
+  for (auto idx : scaleIdx) {
+    if (idx < 0) {
+      in.close();
+      return {};
+    }
+  }
+  for (auto idx : rotIdx) {
+    if (idx < 0) {
+      in.close();
+      return {};
+    }
+  }
+  for (auto idx : alphaIdx) {
+    if (idx < 0) {
+      in.close();
+      return {};
+    }
+  }
+  for (auto idx : colorIdx) {
+    if (idx < 0) {
+      in.close();
+      return {};
+    }
+  }
+
+  // Spherical harmonics are optional and variable in size (depending on degree)
+  std::vector<int> shIdx;
+  for (int32_t i = 0; i < 45; i++) {
+    const auto &itr = fields.find("f_rest_" + std::to_string(i));
+    if (itr == fields.end())
+      break;
+    shIdx.push_back(itr->second);
+  }
+  const int32_t shDim = static_cast<int>(shIdx.size() / 3);
+
+  std::vector<float> values(numPoints * fields.size());
+  in.read(reinterpret_cast<char *>(values.data()), values.size() * sizeof(float));
+  if (!in.good()) {
+    SpzLog("[SPZ ERROR] Unable to load data from: %s", filename.c_str());
+    in.close();
+    return {};
+  }
+  in.close();
+
+  GaussianCloud result;
+  result.numPoints = numPoints;
+  result.shDegree = degreeForDim(shDim);
+  result.positions.reserve(numPoints * 3);
+  result.scales.reserve(numPoints * 3);
+  result.rotations.reserve(numPoints * 4);
+  result.alphas.reserve(numPoints * 1);
+  result.colors.reserve(numPoints * 3);
+  for (size_t i = 0; i < values.size(); i += fields.size()) {
+    for (int32_t j = 0; j < positionIdx.size(); j++) {
+      result.positions.push_back(values[i + positionIdx[j]]);
+    }
+    for (int32_t j = 0; j < scaleIdx.size(); j++) {
+      result.scales.push_back(values[i + scaleIdx[j]]);
+    }
+    for (int32_t j = 0; j < rotIdx.size(); j++) {
+      result.rotations.push_back(values[i + rotIdx[j]]);
+    }
+    for (int32_t j = 0; j < alphaIdx.size(); j++) {
+      result.alphas.push_back(values[i + alphaIdx[j]]);
+    }
+    for (int32_t j = 0; j < colorIdx.size(); j++) {
+      result.colors.push_back(values[i + colorIdx[j]]);
+    }
+    // Convert from [N,C,S] to [N,S,C] (where C is color channel, S is SH coeff).
+    for (int32_t j = 0; j < shDim; j++) {
+      result.sh.push_back(values[i + shIdx[j]]);
+      result.sh.push_back(values[i + shIdx[j + shDim]]);
+      result.sh.push_back(values[i + shIdx[j + 2 * shDim]]);
+    }
+  }
+
+  result.convertCoordinates(CoordinateSystem::RDF, o.to);
+  return result;
+}
+
+bool saveSplatToPly(const GaussianCloud &data, const PackOptions &o, const std::string &filename) {
+  const int32_t N = data.numPoints;
+  CHECK_EQ(data.positions.size(), N * 3);
+  CHECK_EQ(data.scales.size(), N * 3);
+  CHECK_EQ(data.rotations.size(), N * 4);
+  CHECK_EQ(data.alphas.size(), N);
+  CHECK_EQ(data.colors.size(), N * 3);
+  const int32_t shDim = static_cast<int>(data.sh.size() / N / 3);
+  const int32_t D = 17 + shDim * 3;
+
+  CoordinateConverter c = coordinateConverter(o.from, CoordinateSystem::RDF);
+
+  std::vector<float> values(N * D, 0.0f);
+  int32_t outIdx = 0, i3 = 0, i4 = 0;
+  for (int32_t i = 0; i < N; i++) {
+    // Position (x, y, z)
+    values[outIdx++] = c.flipP[0] * data.positions[i3 + 0];
+    values[outIdx++] = c.flipP[1] * data.positions[i3 + 1];
+    values[outIdx++] = c.flipP[2] * data.positions[i3 + 2];
+    // Normals (nx, ny, nz): these are always zero, but some viewers expect them to be present
+    outIdx += 3;
+    // Color (r, g, b): DC component for spherical harmonics
+    values[outIdx++] = data.colors[i3 + 0];
+    values[outIdx++] = data.colors[i3 + 1];
+    values[outIdx++] = data.colors[i3 + 2];
+    // Spherical harmonics: Interleave so the coefficients are the fastest-changing axis and
+    // the channel (r, g, b) is slower-changing axis.
+    for (int32_t j = 0; j < shDim; j++) {
+      values[outIdx++] = c.flipSh[j] * data.sh[(i * shDim + j) * 3];
+    }
+    for (int32_t j = 0; j < shDim; j++) {
+      values[outIdx++] = c.flipSh[j] * data.sh[(i * shDim + j) * 3 + 1];
+    }
+    for (int32_t j = 0; j < shDim; j++) {
+      values[outIdx++] = c.flipSh[j] * data.sh[(i * shDim + j) * 3 + 2];
+    }
+    // Alpha
+    values[outIdx++] = data.alphas[i];
+    // Scale (sx, sy, sz)
+    values[outIdx++] = data.scales[i3 + 0];
+    values[outIdx++] = data.scales[i3 + 1];
+    values[outIdx++] = data.scales[i3 + 2];
+    // Rotation (qw, qx, qy, qz)
+    values[outIdx++] = data.rotations[i4 + 3];
+    values[outIdx++] = c.flipQ[0] * data.rotations[i4 + 0];
+    values[outIdx++] = c.flipQ[1] * data.rotations[i4 + 1];
+    values[outIdx++] = c.flipQ[2] * data.rotations[i4 + 2];
+    i3 += 3;
+    i4 += 4;
+  }
+  CHECK_EQ(outIdx, values.size());
+
+  std::ofstream out(filename, std::ios::binary);
+  if (!out.good()) {
+    SpzLog("[SPZ ERROR] Unable to open for writing: %s", filename.c_str());
+    return false;
+  }
+  out << "ply\n";
+  out << "format binary_little_endian 1.0\n";
+  out << "element vertex " << N << "\n";
+  out << "property float x\n";
+  out << "property float y\n";
+  out << "property float z\n";
+  out << "property float nx\n";
+  out << "property float ny\n";
+  out << "property float nz\n";
+  out << "property float f_dc_0\n";
+  out << "property float f_dc_1\n";
+  out << "property float f_dc_2\n";
+  for (int32_t i = 0; i < shDim * 3; i++) {
+    out << "property float f_rest_" << i << "\n";
+  }
+  out << "property float opacity\n";
+  out << "property float scale_0\n";
+  out << "property float scale_1\n";
+  out << "property float scale_2\n";
+  out << "property float rot_0\n";
+  out << "property float rot_1\n";
+  out << "property float rot_2\n";
+  out << "property float rot_3\n";
+  out << "end_header\n";
+  out.write(reinterpret_cast<char *>(values.data()), values.size() * sizeof(float));
+  out.close();
+  if (!out.good()) {
+    SpzLog("[SPZ ERROR] Failed to write to: %s", filename.c_str());
+    return false;
+  }
+  return true;
+}
+
+}  // namespace spz

SplatTiler/spz/load-spz.h

@@ -0,0 +1,101 @@
+#pragma once
+#include <array>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "splat-types.h"
+
+namespace spz {
+
+// Represents a single inflated gaussian. Each gaussian has 236 bytes. Although the data is easier
+// to intepret in this format, it is not more precise than the packed format, since it was inflated.
+struct UnpackedGaussian {
+  std::array<float, 3> position;  // x, y, z
+  std::array<float, 4> rotation;  // x, y, z, w
+  std::array<float, 3> scale;     // std::log(scale)
+  std::array<float, 3> color;     // rgb sh0 encoding
+  float alpha;                    // inverse logistic
+  std::array<float, 15> shR;
+  std::array<float, 15> shG;
+  std::array<float, 15> shB;
+};
+
+// Represents a single low precision gaussian. Each gaussian has exactly 65 bytes, even if it does
+// not have full spherical harmonics.
+struct PackedGaussian {
+  std::array<uint8_t, 9> position{};
+  std::array<uint8_t, 4> rotation{};
+  std::array<uint8_t, 3> scale{};
+  std::array<uint8_t, 3> color{};
+  uint8_t alpha = 0;
+  std::array<uint8_t, 15> shR{};
+  std::array<uint8_t, 15> shG{};
+  std::array<uint8_t, 15> shB{};
+
+  UnpackedGaussian unpack(
+    bool usesFloat16,  bool usesQuaternionSmallestThree, int32_t fractionalBits, const CoordinateConverter &c) const;
+};
+
+// Represents a full splat with lower precision. Each splat has at most 64 bytes, although splats
+// with fewer spherical harmonics degrees will have less. The data is stored non-interleaved.
+struct PackedGaussians {
+  int32_t numPoints = 0;       // Total number of points (gaussians)
+  int32_t shDegree = 0;        // Degree of spherical harmonics
+  int32_t fractionalBits = 0;  // Number of bits used for fractional part of fixed-point coords
+  bool antialiased = false;    // Whether gaussians should be rendered with mip-splat antialiasing
+  bool usesQuaternionSmallestThree = true; // Whether gaussians use the smallest three method to store quaternions
+
+  std::vector<uint8_t> positions;
+  std::vector<uint8_t> scales;
+  std::vector<uint8_t> rotations;
+  std::vector<uint8_t> alphas;
+  std::vector<uint8_t> colors;
+  std::vector<uint8_t> sh;
+
+  bool usesFloat16() const;
+  PackedGaussian at(int32_t i) const;
+  UnpackedGaussian unpack(int32_t i, const CoordinateConverter &c) const;
+};
+
+struct PackOptions {
+  CoordinateSystem from = CoordinateSystem::UNSPECIFIED;
+};
+
+struct UnpackOptions {
+  CoordinateSystem to = CoordinateSystem::UNSPECIFIED;
+};
+
+// Saves Gaussian splat in packed format, returning a vector of bytes.
+bool saveSpz(
+  const GaussianCloud &gaussians, const PackOptions &options, std::vector<uint8_t> *output);
+
+// Loads Gaussian splat from a vector of bytes in packed format.
+GaussianCloud loadSpz(const std::vector<uint8_t> &data, const UnpackOptions &options);
+
+// Loads Gaussian splat from a vector of bytes in packed format.
+PackedGaussians loadSpzPacked(const std::string &filename);
+PackedGaussians loadSpzPacked(const uint8_t *data, int32_t size);
+PackedGaussians loadSpzPacked(const std::vector<uint8_t> &data);
+
+// Saves Gaussian splat in packed format to a file
+bool saveSpz(
+  const GaussianCloud &gaussians, const PackOptions &options, const std::string &filename);
+
+// Loads Gaussian splat from a file in packed format
+GaussianCloud loadSpz(const std::string &filename, const UnpackOptions &o);
+
+// Loads Gaussian splat from a byte pointer in packed format.
+GaussianCloud loadSpz(const uint8_t *data, int32_t size, const UnpackOptions &options);
+
+// Saves Gaussian splat data in .ply format
+bool saveSplatToPly(
+  const spz::GaussianCloud &gaussians, const PackOptions &options, const std::string &filename);
+
+// Loads Gaussian splat data in .ply format
+GaussianCloud loadSplatFromPly(const std::string &filename, const UnpackOptions &options);
+
+void serializePackedGaussians(const PackedGaussians &packed, std::ostream *out);
+
+bool compressGzipped(const uint8_t *data, size_t size, std::vector<uint8_t> *out);
+}  // namespace spz

SplatTiler/spz/splat-c-types.cc

@@ -0,0 +1,3 @@
+#include "splat-c-types.h"
+
+// Empty.

SplatTiler/spz/splat-c-types.h

@@ -0,0 +1,28 @@
+#ifndef SPZ_SPLAT_C_TYPES_H_
+#define SPZ_SPLAT_C_TYPES_H_
+
+#define _USE_MATH_DEFINES
+#include <math.h>
+#include <stddef.h>
+#include <stdint.h>
+
+// These types are used to bridge between the C++ API and C (to interop with Swift and C#).
+
+typedef struct {
+  size_t count;
+  float *data;
+} SpzFloatBuffer;
+
+typedef struct {
+  int32_t numPoints;
+  int32_t shDegree;
+  bool antialiased;
+  SpzFloatBuffer positions;
+  SpzFloatBuffer scales;
+  SpzFloatBuffer rotations;
+  SpzFloatBuffer alphas;
+  SpzFloatBuffer colors;
+  SpzFloatBuffer sh;
+} GaussianCloudData;
+
+#endif  // SPZ_SPLAT_C_TYPES_H_

SplatTiler/spz/splat-types.cc

@@ -0,0 +1,98 @@
+#include "splat-types.h"
+
+#include <cmath>
+#include <limits>
+
+namespace spz {
+
+float halfToFloat(Half h) {
+  auto sgn = ((h >> 15) & 0x1);
+  auto exponent = ((h >> 10) & 0x1f);
+  auto mantissa = h & 0x3ff;
+
+  float signMul = sgn == 1 ? -1.0 : 1.0;
+  if (exponent == 0) {
+    // Subnormal numbers (no exponent, 0 in the mantissa decimal).
+    return signMul * std::pow(2.0f, -14.0f) * static_cast<float>(mantissa) / 1024.0f;
+  }
+
+  if (exponent == 31) {
+    // Infinity or NaN.
+    return mantissa != 0 ? std::numeric_limits<float>::quiet_NaN() : signMul * std::numeric_limits<float>::infinity();
+  }
+
+  // non-zero exponent implies 1 in the mantissa decimal.
+  return signMul * std::pow(2.0f, static_cast<float>(exponent) - 15.0f)
+    * (1.0f + static_cast<float>(mantissa) / 1024.0f);
+}
+
+Half floatToHalf(float f) {
+  uint32_t f32 = *reinterpret_cast<uint32_t *>(&f);
+  int32_t sign = (f32 >> 31) & 0x01;        // 1 bit   -> 1 bit
+  int32_t exponent = ((f32 >> 23) & 0xff);  // 8 bits  -> 5 bits
+  int32_t mantissa = f32 & 0x7fffff;        // 23 bits -> 10 bits
+
+  // Handle inf and nan from float.
+  if (exponent == 0xFF) {
+    if (mantissa == 0) {
+      return (sign << 15) | 0x7C00; // Inf
+    }
+
+    return (sign << 15) | 0x7C01;  // Nan
+  }
+
+  // If the exponent is greater than the range of half, return +/- Inf.
+  int32_t centeredExp = exponent - 127;
+  if (centeredExp > 15) {
+    return (sign << 15) | 0x7C00;
+  }
+
+  // Normal numbers. centeredExp = [-15, 15]
+  if (centeredExp > -15) {
+    return (sign << 15) | ((centeredExp + 15) << 10) | (mantissa >> 13);
+  }
+
+  // Subnormal numbers.
+  int32_t fullMantissa = 0x800000 | mantissa;
+  int32_t shift = -(centeredExp + 14);  // Shift is in [-1 to -113]
+  int32_t newMantissa = fullMantissa >> shift;
+  return (sign << 15) | (newMantissa >> 13);
+}
+
+float norm(const Vec3f &a) {
+  return std::sqrt(squaredNorm(a));
+}
+
+Vec3f normalized(const Vec3f &v) {
+  float n = norm(v);
+  return {v[0] / n, v[1] / n, v[2] / n};
+}
+
+Quat4f normalized(const Quat4f &v) {
+  float norm = std::sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2] + v[3] * v[3]);
+  return {v[0] / norm, v[1] / norm, v[2] / norm, v[3] / norm};
+}
+
+float norm(const Quat4f &q) {
+  return std::sqrt(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]);
+}
+
+Quat4f axisAngleQuat(const Vec3f &scaledAxis) {
+  const float &a0 = scaledAxis[0];
+  const float &a1 = scaledAxis[1];
+  const float &a2 = scaledAxis[2];
+  const float thetaSquared = a0 * a0 + a1 * a1 + a2 * a2;
+  // For points not at the origin, the full conversion is numerically stable.
+  if (thetaSquared > 0.0f) {
+    const float theta = std::sqrt(thetaSquared);
+    const float halfTheta = theta * 0.5f;
+    const float k = std::sin(halfTheta) / theta;
+    return normalized(std::array<float, 4>{std::cos(halfTheta), a0 * k, a1 * k, a2 * k});
+  }
+  // If thetaSquared is 0, then we will get NaNs when dividing by theta.  By approximating with a
+  // Taylor series, and truncating at one term, the value will be computed correctly.
+  const float k = 0.5f;
+  return normalized(Quat4f{1.0f, a0 * k, a1 * k, a2 * k});
+}
+
+}  // namespace spz

SplatTiler/spz/splat-types.h

@@ -0,0 +1,266 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <cstring>
+#include <vector>
+
+#include "splat-c-types.h"
+
+namespace spz {
+
+inline SpzFloatBuffer copyFloatBuffer(const std::vector<float> &vector) {
+  SpzFloatBuffer buffer = {0, nullptr};
+  if (!vector.empty()) {
+    buffer.count = vector.size();
+    buffer.data = new float[buffer.count];
+    std::memcpy(buffer.data, vector.data(), buffer.count * sizeof(float));
+  }
+  return buffer;
+}
+
+enum class CoordinateSystem {
+  UNSPECIFIED = 0,
+  LDB = 1,  // Left Down Back
+  RDB = 2,  // Right Down Back
+  LUB = 3,  // Left Up Back
+  RUB = 4,  // Right Up Back, Three.js coordinate system
+  LDF = 5,  // Left Down Front
+  RDF = 6,  // Right Down Front, PLY coordinate system
+  LUF = 7,  // Left Up Front, GLB coordinate system
+  RUF = 8,  // Right Up Front, Unity coordinate system
+};
+
+struct CoordinateConverter {
+  std::array<float, 3> flipP = {1.0f, 1.0f, 1.0f};  // x, y, z flips.
+  std::array<float, 3> flipQ = {1.0f, 1.0f, 1.0f};  // x, y, z flips, w is never flipped.
+  std::array<float, 15> flipSh =  // Flips for the 15 spherical harmonics coefficients.
+    {1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f};
+};
+
+constexpr std::array<bool, 3> axesMatch(CoordinateSystem a, CoordinateSystem b) {
+  auto aNum = static_cast<int>(a) - 1;
+  auto bNum = static_cast<int>(b) - 1;
+  if (aNum < 0 || bNum < 0) {
+    return {true, true, true};
+  }
+  return {
+    ((aNum >> 0) & 1) == ((bNum >> 0) & 1),
+    ((aNum >> 1) & 1) == ((bNum >> 1) & 1),
+    ((aNum >> 2) & 1) == ((bNum >> 2) & 1)};
+}
+
+constexpr CoordinateConverter coordinateConverter(CoordinateSystem from, CoordinateSystem to) {
+  auto [xMatch, yMatch, zMatch] = axesMatch(from, to);
+  float x = xMatch ? 1.0f : -1.0f;
+  float y = yMatch ? 1.0f : -1.0f;
+  float z = zMatch ? 1.0f : -1.0f;
+  return CoordinateConverter{
+    {x, y, z},
+    {y * z, x * z, x * y},
+    {
+      y,          // 0
+      z,          // 1
+      x,          // 2
+      x * y,      // 3
+      y * z,      // 4
+      1.0f,       // 5
+      x * z,      // 6
+      1.0f,       // 7
+      y,          // 8
+      x * y * z,  // 9
+      y,          // 10
+      z,          // 11
+      x,          // 12
+      z,          // 13
+      x           // 14
+    }
+  };
+}
+
+// A point cloud composed of Gaussians. Each gaussian is represented by:
+//   - xyz position
+//   - xyz scales (on log scale, compute exp(x) to get scale factor)
+//   - xyzw quaternion
+//   - alpha (before sigmoid activation, compute sigmoid(a) to get alpha value between 0 and 1)
+//   - rgb color (as SH DC component, compute 0.5 + 0.282095 * x to get color value between 0 and 1)
+//   - 0 to 45 spherical harmonics coefficients (see comment below)
+struct GaussianCloud {
+  // Total number of points (gaussians) in this splat.
+  int32_t numPoints = 0;
+
+  // Degree of spherical harmonics for this splat.
+  int32_t shDegree = 0;
+
+  // Whether the gaussians should be rendered in antialiased mode (mip splatting)
+  bool antialiased = false;
+
+  // See block comment above for details
+  std::vector<float> positions;
+  std::vector<float> scales;
+  std::vector<float> rotations;
+  std::vector<float> alphas;
+  std::vector<float> colors;
+
+  // Spherical harmonics coefficients. The number of coefficients per point depends on shDegree:
+  //   0 -> 0
+  //   1 -> 9   (3 coeffs x 3 channels)
+  //   2 -> 24  (8 coeffs x 3 channels)
+  //   3 -> 45  (15 coeffs x 3 channels)
+  // The color channel is the inner (fastest varying) axis, and the coefficient is the outer
+  // (slower varying) axis, i.e. for degree 1, the order of the 9 values is:
+  //   sh1n1_r, sh1n1_g, sh1n1_b, sh10_r, sh10_g, sh10_b, sh1p1_r, sh1p1_g, sh1p1_b
+  std::vector<float> sh;
+
+  // The caller is responsible for freeing the pointers in the returned GaussianCloudData
+  GaussianCloudData data() const {
+    GaussianCloudData data;
+    data.numPoints = numPoints;
+    data.shDegree = shDegree;
+    data.antialiased = antialiased;
+    data.positions = copyFloatBuffer(positions);
+    data.scales = copyFloatBuffer(scales);
+    data.rotations = copyFloatBuffer(rotations);
+    data.alphas = copyFloatBuffer(alphas);
+    data.colors = copyFloatBuffer(colors);
+    data.sh = copyFloatBuffer(sh);
+    return data;
+  }
+
+  // Convert between two coordinate systems, for example from RDF (ply format) to RUB (used by spz).
+  // This is performed in-place.
+  void convertCoordinates(CoordinateSystem from, CoordinateSystem to) {
+    if (numPoints == 0) {
+      // There is nothing to convert.
+      return;
+    }
+    CoordinateConverter c = coordinateConverter(from, to);
+    for (size_t i = 0; i < positions.size(); i += 3) {
+      positions[i + 0] *= c.flipP[0];
+      positions[i + 1] *= c.flipP[1];
+      positions[i + 2] *= c.flipP[2];
+    }
+    for (size_t i = 0; i < rotations.size(); i += 4) {
+      rotations[i + 0] *= c.flipQ[0];
+      rotations[i + 1] *= c.flipQ[1];
+      rotations[i + 2] *= c.flipQ[2];
+      // Don't modify rotations[i + 3] (w component)
+    }
+    // Rotate spherical harmonics by inverting coefficients that reference the y and z axes, for
+    // each RGB channel. See spherical_harmonics_kernel_impl.h for spherical harmonics formulas.
+    const size_t numCoeffs = sh.size() / 3;
+    const size_t numCoeffsPerPoint = numCoeffs / numPoints;
+    size_t idx = 0;
+    for (size_t i = 0; i < numCoeffs; i += numCoeffsPerPoint) {
+      for (size_t j = 0; j < numCoeffsPerPoint; ++j, idx += 3) {
+        auto flip = c.flipSh[j];
+        sh[idx + 0] *= flip;
+        sh[idx + 1] *= flip;
+        sh[idx + 2] *= flip;
+      }
+    }
+  }
+
+  // Rotates the GaussianCloud by 180 degrees about the x axis (converts from RUB to RDF coordinates
+  // and vice versa. This is performed in-place.
+  void rotate180DegAboutX() { convertCoordinates(CoordinateSystem::RUB, CoordinateSystem::RDF); }
+
+  float medianVolume() const {
+    if (numPoints == 0) {
+      return 0.01f;
+    }
+    // The volume of an ellipsoid is 4/3 * pi * x * y * z, where x, y, and z are the radii on each
+    // axis. Scales are stored on a log scale, and exp(x) * exp(y) * exp(z) = exp(x + y + z). So we
+    // can sort by value = (x + y + z) and compute volume = 4/3 * pi * exp(value) later.
+    std::vector<float> scaleSums;
+    for (size_t i = 0; i < scales.size(); i += 3) {
+      float sum = scales[i] + scales[i + 1] + scales[i + 2];
+      scaleSums.push_back(sum);
+    }
+    std::sort(scaleSums.begin(), scaleSums.end());
+    float median = scaleSums[scaleSums.size() / 2];
+    return (M_PI * 4 / 3) * exp(median);
+  }
+};
+
+// SPZ Splat math helpers, lightweight implementations of vector and quaternion math.
+using Vec3f = std::array<float, 3>;   // x, y, z
+using Quat4f = std::array<float, 4>;  // w, x, y, z
+using Half = uint16_t;
+
+// Half-precision helpers.
+float halfToFloat(Half h);
+Half floatToHalf(float f);
+
+// Vector helpers.
+Vec3f normalized(const Vec3f &v);
+float norm(const Vec3f &a);
+
+// Quaternion helpers.
+float norm(const Quat4f &q);
+Quat4f normalized(const Quat4f &v);
+Quat4f axisAngleQuat(const Vec3f &scaledAxis);
+
+// Constexpr helpers.
+constexpr Vec3f vec3f(const float *data) { return {data[0], data[1], data[2]}; }
+
+constexpr float dot(const Vec3f &a, const Vec3f &b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+constexpr float squaredNorm(const Vec3f &v) { return dot(v, v); }
+
+constexpr Quat4f quat4f(const float *data) { return {data[0], data[1], data[2], data[3]}; }
+
+constexpr Vec3f times(const Quat4f &q, const Vec3f &p) {
+  auto [w, x, y, z] = q;
+  auto [vx, vy, vz] = p;
+  auto x2 = x + x;
+  auto y2 = y + y;
+  auto z2 = z + z;
+  auto wx2 = w * x2;
+  auto wy2 = w * y2;
+  auto wz2 = w * z2;
+  auto xx2 = x * x2;
+  auto xy2 = x * y2;
+  auto xz2 = x * z2;
+  auto yy2 = y * y2;
+  auto yz2 = y * z2;
+  auto zz2 = z * z2;
+  return {
+    vx * (1.0f - (yy2 + zz2)) + vy * (xy2 - wz2) + vz * (xz2 + wy2),
+    vx * (xy2 + wz2) + vy * (1.0f - (xx2 + zz2)) + vz * (yz2 - wx2),
+    vx * (xz2 - wy2) + vy * (yz2 + wx2) + vz * (1.0f - (xx2 + yy2))};
+}
+
+inline Quat4f times(const Quat4f &a, const Quat4f &b) {
+  auto [w, x, y, z] = a;
+  auto [qw, qx, qy, qz] = b;
+  return normalized(std::array<float, 4>{
+    w * qw - x * qx - y * qy - z * qz,
+    w * qx + x * qw + y * qz - z * qy,
+    w * qy - x * qz + y * qw + z * qx,
+    w * qz + x * qy - y * qx + z * qw});
+}
+
+constexpr Quat4f times(const Quat4f &a, float s) {
+  return {a[0] * s, a[1] * s, a[2] * s, a[3] * s};
+}
+
+constexpr Quat4f plus(const Quat4f &a, const Quat4f &b) {
+  return {a[0] + b[0], a[1] + b[1], a[2] + b[2], a[3] + b[3]};
+}
+
+constexpr Vec3f times(const Vec3f &v, float s) { return {v[0] * s, v[1] * s, v[2] * s}; }
+
+constexpr Vec3f plus(const Vec3f &a, const Vec3f &b) {
+  return {a[0] + b[0], a[1] + b[1], a[2] + b[2]};
+}
+
+constexpr Vec3f times(const Vec3f &a, const Vec3f &b) {
+  return {a[0] * b[0], a[1] * b[1], a[2] * b[2]};
+}
+
+}  // namespace spz

client/.env.development

@@ -0,0 +1,4 @@
+VITE_AWS_REGION=us-east-2
+VITE_AWS_COGNITO_IDENTITY_POOL_ID=us-east-2:1387102d-5a87-4742-8a69-1baa70f37984
+VITE_S3_BUCKET=ddy-first-bucket
+VITE_CESIUM_ION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxNDM0OThmMS01NjBmLTQzNTYtYjQ0MC0yMWY0ZGExZjk0ZjEiLCJpZCI6MjM2MjE1LCJpYXQiOjE3MjQyNzQ4MjB9.6XHQrKm0KGDFRZSg5veN64KaxYT3ekGj2qprsbEiI7k

client/.env.example

@@ -0,0 +1,25 @@
+# AWS Configuration for GDACloud Frontend
+# Copy this file to .env.local and fill in your actual values
+
+# AWS Region where your S3 bucket and Cognito Identity Pool are located
+VITE_AWS_REGION=us-east-2
+
+# Cognito Identity Pool ID for unauthenticated access
+# Format: region:uuid (e.g., us-east-2:12345678-1234-1234-1234-123456789012)
+# Create this in AWS Cognito console:
+# - Identity Pools -> Create New Identity Pool
+# - Allow unauthenticated identities
+# - Attach IAM role with S3 GetObject permissions
+VITE_AWS_COGNITO_IDENTITY_POOL_ID=us-east-2:YOUR_IDENTITY_POOL_ID
+
+# S3 Bucket name containing your 3D tile assets
+VITE_S3_BUCKET=ddy-first-bucket
+
+# Cesium Ion Token (optional, for Cesium base maps)
+# Get token from https://ion.cesiumjs.com
+VITE_CESIUM_ION_TOKEN=YOUR_CESIUM_ION_TOKEN
+
+# GitHub Pages deployment base path
+# For repository deployment: /repository-name/
+# For custom domain or local: /
+BASE_PATH=/

client/.env.production

@@ -0,0 +1,4 @@
+VITE_AWS_REGION=us-east-2
+VITE_AWS_COGNITO_IDENTITY_POOL_ID=us-east-2:1387102d-5a87-4742-8a69-1baa70f37984
+VITE_S3_BUCKET=ddy-first-bucket
+VITE_CESIUM_ION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxNDM0OThmMS01NjBmLTQzNTYtYjQ0MC0yMWY0ZGExZjk0ZjEiLCJpZCI6MjM2MjE1LCJpYXQiOjE3MjQyNzQ4MjB9.6XHQrKm0KGDFRZSg5veN64KaxYT3ekGj2qprsbEiI7k

client/README.md

@@ -0,0 +1,16 @@
+# React + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.

client/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>front-end</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

client/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "front-end",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.509.0",
+    "@aws-sdk/credential-provider-cognito-identity": "^3.509.0",
+    "@aws-sdk/s3-request-presigner": "^3.509.0",
+    "@aws-sdk/util-endpoints": "^3.509.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^7.3.4",
+    "@mui/material": "^7.3.4",
+    "cesium": "^1.134.1",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "resium": "^1.19.0-beta.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^5.0.4",
+    "eslint": "^9.36.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.22",
+    "gh-pages": "^6.3.0",
+    "globals": "^16.4.0",
+    "terser": "^5.43.1",
+    "vite": "^7.1.7",
+    "vite-plugin-cesium": "^1.2.23"
+  }
+}

client/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

client/src/App.jsx

@@ -0,0 +1,28 @@
+import React, { useEffect } from "react";
+import Home from "./pages/Home";
+import VisitLog from "./pages/VisitLog";
+import { recordVisit } from "./utils/visitorTracking";
+
+function App() {
+  const visitLogPath =
+    import.meta.env.VITE_VISIT_LOG_PATH || "/visits-admin";
+  const isVisitPage = window.location.pathname === visitLogPath;
+
+  useEffect(() => {
+    if (!isVisitPage) {
+      recordVisit();
+    }
+  }, [isVisitPage]);
+
+  if (isVisitPage) {
+    return <VisitLog />;
+  }
+
+  return (
+    <div className="App">
+      <Home />
+    </div>
+  );
+}
+
+export default App;

client/src/cesiumSetup.js

@@ -0,0 +1,2 @@
+// Ensure Cesium assets resolve correctly under GitHub Pages base path
+window.CESIUM_BASE_URL = `${import.meta.env.BASE_URL}cesium/`

client/src/components/CesiumViewer.jsx

@@ -0,0 +1,501 @@
+import React, {
+  useRef,
+  useEffect,
+  useState,
+  forwardRef,
+  useImperativeHandle,
+} from "react";
+import { Viewer } from "resium";
+import * as Cesium from "cesium";
+import { Entity } from "resium";
+import { Cartesian3, Color, Matrix3, Quaternion } from "cesium";
+
+// Cesium Ion token is safe to embed in client code (not a secret)
+Cesium.Ion.defaultAccessToken =
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxNDM0OThmMS01NjBmLTQzNTYtYjQ0MC0yMWY0ZGExZjk0ZjEiLCJpZCI6MjM2MjE1LCJpYXQiOjE3MjQyNzQ4MjB9.6XHQrKm0KGDFRZSg5veN64KaxYT3ekGj2qprsbEiI7k";
+
+function offsetTilesetHeight(tileset, offsetMeters) {
+  const boundingSphere = tileset.boundingSphere;
+  const center = boundingSphere.center;
+
+  // Get normalized up direction in ECEF
+  const up = Cesium.Cartesian3.normalize(center, new Cesium.Cartesian3());
+
+  // Compute translation vector = up * offset
+  const translation = Cesium.Cartesian3.multiplyByScalar(
+    up,
+    offsetMeters,
+    new Cesium.Cartesian3(),
+  );
+  // Build translation matrix in ECEF
+  const translationMatrix = Cesium.Matrix4.fromTranslation(translation);
+  // Apply to existing transform
+  const finalMatrix = Cesium.Matrix4.multiplyTransformation(
+    translationMatrix,
+    tileset.modelMatrix,
+    new Cesium.Matrix4(),
+  );
+  tileset.modelMatrix = finalMatrix;
+}
+
+function unoffsetECEFPoint(x, y, z, tileset, offsetMeters) {
+  const center = tileset.boundingSphere.center;
+
+  // Normalized up direction (same as used during offset)
+  const up = Cesium.Cartesian3.normalize(center, new Cesium.Cartesian3());
+
+  // Translation applied to tileset
+  const offset = Cesium.Cartesian3.multiplyByScalar(
+    up,
+    offsetMeters,
+    new Cesium.Cartesian3()
+  );
+
+  // Subtract offset to revert point
+  const original = Cesium.Cartesian3.subtract(
+    new Cesium.Cartesian3(x, y, z),
+    offset,
+    new Cesium.Cartesian3()
+  );
+
+  return { x: original.x, y: original.y, z: original.z };
+}
+
+function undoTilesetTransformXYZ(x, y, z, tileset) {
+  const ecefPoint = new Cesium.Cartesian3(x, y, z);
+
+  // Compute inverse of current modelMatrix
+  const inverseMatrix = Cesium.Matrix4.inverse(
+    tileset.modelMatrix,
+    new Cesium.Matrix4()
+  );
+
+  // Transform point back
+  const originalPoint = Cesium.Matrix4.multiplyByPoint(
+    inverseMatrix,
+    ecefPoint,
+    new Cesium.Cartesian3()
+  );
+
+  // Return plain numbers
+  return {
+    x: originalPoint.x,
+    y: originalPoint.y,
+    z: originalPoint.z
+  };
+}
+
+function rotateTileset(tileset, rotationMatrix3) {
+  // Convert 3x3 rotation into 4x4 matrix
+  const rotationMatrix4 = Cesium.Matrix4.fromRotation(
+    rotationMatrix3,
+    new Cesium.Matrix4()
+  );
+
+  // Apply rotation *before* the existing model matrix
+  Cesium.Matrix4.multiply(
+    rotationMatrix4,
+    tileset.modelMatrix,
+    tileset.modelMatrix
+  );
+}
+
+function scaleTileset(tileset, scaleX, scaleY, scaleZ) {
+  const scaleMatrix = Cesium.Matrix4.fromScale(
+    new Cesium.Cartesian3(scaleX, scaleY, scaleZ),
+    new Cesium.Matrix4()
+  );
+
+  Cesium.Matrix4.multiply(
+    scaleMatrix,
+    tileset.modelMatrix,
+    tileset.modelMatrix
+  );
+}
+
+
+
+function ecefToLatLonAlt(x, y, z) {
+  const ecef = new Cesium.Cartesian3(x, y, z);
+  const carto = Cesium.Cartographic.fromCartesian(ecef, Cesium.Ellipsoid.WGS84);
+
+  return {
+    lat: Cesium.Math.toDegrees(carto.latitude),
+    lon: Cesium.Math.toDegrees(carto.longitude),
+    alt: carto.height,
+  };
+}
+
+/**
+ * Pure JS implementation of ray intersection (Least Squares)
+ * Replaces the backend /api/compute-intersection
+ */
+function computeIntersectionLocal(measurements) {
+  if (measurements.length < 2) return null;
+
+  const n = measurements.length;
+  let sumIminusDDt = new Cesium.Matrix3(0, 0, 0, 0, 0, 0, 0, 0, 0);
+  let sumIminusDDtO = new Cesium.Cartesian3(0, 0, 0);
+
+  measurements.forEach((m) => {
+    const origin = new Cesium.Cartesian3(m.camera.x, m.camera.y, m.camera.z);
+    const target = new Cesium.Cartesian3(m.point.x, m.point.y, m.point.z);
+    const direction = Cesium.Cartesian3.normalize(
+      Cesium.Cartesian3.subtract(target, origin, new Cesium.Cartesian3()),
+      new Cesium.Cartesian3()
+    );
+
+    // I - d*d^T
+    const d = direction;
+    const m_ddt = [
+      1 - d.x * d.x, -d.x * d.y, -d.x * d.z,
+      -d.y * d.x, 1 - d.y * d.y, -d.y * d.z,
+      -d.z * d.x, -d.z * d.y, 1 - d.z * d.z,
+    ];
+    const mat = Cesium.Matrix3.fromArray(m_ddt);
+
+    // Accumulate matrices
+    Cesium.Matrix3.add(sumIminusDDt, mat, sumIminusDDt);
+
+    // Accumulate (I - d*d^T) * origin
+    const termO = Cesium.Matrix3.multiplyByVector(mat, origin, new Cesium.Cartesian3());
+    Cesium.Cartesian3.add(sumIminusDDtO, termO, sumIminusDDtO);
+  });
+
+  const inverseSum = Cesium.Matrix3.inverse(sumIminusDDt, new Cesium.Matrix3());
+  if (!inverseSum) return null;
+
+  const x = Cesium.Matrix3.multiplyByVector(inverseSum, sumIminusDDtO, new Cesium.Cartesian3());
+
+  // Calculate Residuals and Variance
+  let sse = 0;
+  measurements.forEach((m) => {
+    const origin = new Cesium.Cartesian3(m.camera.x, m.camera.y, m.camera.z);
+    const target = new Cesium.Cartesian3(m.point.x, m.point.y, m.point.z);
+    const direction = Cesium.Cartesian3.normalize(
+      Cesium.Cartesian3.subtract(target, origin, new Cesium.Cartesian3()),
+      new Cesium.Cartesian3()
+    );
+
+    // Residual vector: v = (I - d*d^T) * (x - origin)
+    const diff = Cesium.Cartesian3.subtract(x, origin, new Cesium.Cartesian3());
+    const dot = Cesium.Cartesian3.dot(direction, diff);
+    const projection = Cesium.Cartesian3.multiplyByScalar(direction, dot, new Cesium.Cartesian3());
+    const residualVec = Cesium.Cartesian3.subtract(diff, projection, new Cesium.Cartesian3());
+
+    sse += Cesium.Cartesian3.magnitudeSquared(residualVec);
+  });
+
+  // Variance factor (Degrees of freedom: 2n - 3)
+  const sigma2 = n > 1 ? sse / (2 * n - 3) : 0.01;
+
+  // Covariance Matrix = sigma2 * (Sum(I - dd^T))^-1
+  const covMat = Cesium.Matrix3.multiplyByScalar(inverseSum, sigma2, new Cesium.Matrix3());
+  const covarianceArray = Cesium.Matrix3.toArray(covMat);
+
+  return {
+    x: x.x,
+    y: x.y,
+    z: x.z,
+    stddev: Math.sqrt(sigma2),
+    // Flattened 3x3 matrix for the component
+    covariance: covarianceArray,
+    status: "ok"
+  };
+}
+
+const CesiumViewer = forwardRef(
+  ({ tilesetUrl, points, onAddPoint, offsetHeight, selectedPoint }, ref) => {
+    const viewerRef = useRef(null);
+    const currentModeRef = useRef("default"); // keep internal mode
+    const [measurements, setMeasurements] = useState([]);
+    const tilesetRef = useRef(null);
+
+    const addMeausure = (cameraPosition, cartesian) => {
+      setMeasurements((prev) => {
+        const id = prev.length + 1; // compute id based on latest state
+        const newMeasurement = {
+          id,
+          camera: {
+            x: cameraPosition.x,
+            y: cameraPosition.y,
+            z: cameraPosition.z,
+          },
+          point: { x: cartesian.x, y: cartesian.y, z: cartesian.z },
+        };
+        console.log("Adding measure:", newMeasurement);
+        return [...prev, newMeasurement];
+      });
+    };
+    // Expose a function to parent
+    useImperativeHandle(ref, () => ({
+      setMode: (newMode) => {
+        currentModeRef.current = newMode;
+        console.log("Cesium mode changed to:", newMode);
+        // TODO: enable/disable measurement handlers, selection handlers, etc.
+        // For example:
+        // if (newMode === "measure") { activateMeasurement(viewerRef.current) }
+        // else if (newMode === "select") { activateSelection(viewerRef.current) }
+      },
+      getMode: () => currentModeRef.current,
+      endMeasure: async () => {
+        if (onAddPoint && measurements.length > 0) {
+          try {
+            const result = computeIntersectionLocal(measurements);
+            if (!result) throw new Error("Could not compute intersection locally");
+
+            const tileset = viewerRef.current.cesiumElement.scene.primitives.get(0);
+            const coord = unoffsetECEFPoint(result.x, result.y, result.z, tileset, offsetHeight);
+            const lla = ecefToLatLonAlt(coord.x, coord.y, coord.z);
+            const point = {
+              lat: lla.lat,
+              lon: lla.lon,
+              alt: lla.alt,
+              x: result.x,
+              y: result.y,
+              z: result.z,
+              accuracy: result.stddev,
+              covariance: result.covariance,
+              measures: [...measurements], // copy of all measures
+            };
+            console.log("Computed intersection point:", point);
+            onAddPoint(point);
+          } catch (err) {
+            console.error("Failed to compute intersection:", err);
+          }
+        }
+        currentModeRef.current = "default";
+        setMeasurements([]);
+      },
+    }));
+
+    // point = {x, y, z}, size in meters, color optional
+    /**
+   * Creates a Cesium Entity to visualize a 3D point and its covariance.
+   *
+   * @param {object} point - The 3D point { x, y, z }.
+   * @param {number[][]} covariance - The 3x3 covariance matrix.
+   * @param {number} [confidenceScale=1.0] - Scale factor for the radii.
+   * - 1.0 = 1-sigma ellipsoid
+   * - 2.795 = 95% confidence ellipsoid (for 3D)
+   * @param {Color} [color=Color.RED.withAlpha(0.5)] - The ellipsoid material.
+   * @param {string} [key] - React key.
+   */
+    // Define the scratch object ONCE for the eigendecomposition
+    const scratchEigen = {
+      diagonal: new Matrix3(),
+      unitary: new Matrix3(),
+    };
+    // --- END ADD ---
+    const createCovarianceEntity = (
+      point,
+      confidenceScale = 1.0,
+      color = Color.RED.withAlpha(0.5),
+      key,
+      selected = false,
+      selectedColor = Color.GREEN.withAlpha(0.7)
+    ) => {
+      // 1. Convert your 2D array into a Cesium Matrix3
+      // Cesium matrices are column-major, so we flatten the array
+      const covMatrix = Matrix3.fromArray(point.covariance.flat());
+      // 2. Perform Eigendecomposition
+      // This finds the orientation (eigenvectors) and variance (eigenvalues)
+      // result.unitary = Rotation matrix (eigenvectors)
+      // result.diagonal = Diagonal matrix of eigenvalues
+      let result;
+      try {
+        result = Matrix3.computeEigenDecomposition(covMatrix, scratchEigen);
+      } catch (e) {
+        console.error("Failed to compute eigendecomposition. Matrix may be singular.", e);
+        return null; // Don't render if math fails
+      }
+      const diagonal = result.diagonal; // Extract diagonal elements
+      const unitary = result.unitary;
+      const length = Math.sqrt(diagonal[0] + diagonal[4] + diagonal[8]) + 1.0e-12;
+
+      // 3. Get the radii (standard deviations)
+      // The radii are the square root of the eigenvalues (on the diagonal)
+      // We apply the confidence scaling factor here.
+      const radii = new Cartesian3(
+        Math.sqrt(diagonal[0]) / length * confidenceScale,
+        Math.sqrt(diagonal[4]) / length * confidenceScale,
+        Math.sqrt(diagonal[8]) / length * confidenceScale
+      );
+      // 4. Get the orientation
+      // Convert the rotation matrix (eigenvectors) into a Quaternion
+      const orientation = Quaternion.fromRotationMatrix(unitary);
+
+      // 5. Create the Entity
+      return (
+        <Entity
+          key={key}
+          position={new Cartesian3(point.x, point.y, point.z)}
+          orientation={orientation}
+          ellipsoid={{
+            radii: radii,
+            material: selected ? selectedColor : color,
+            outline: true,
+            outlineColor: Color.BLACK,
+          }}
+          // The solid center point marker
+          point={{
+            pixelSize: 8,
+            color: selected ? Color.RED : Color.WHITE,
+            outlineColor: Color.BLACK,
+            outlineWidth: 2,
+          }}
+        />
+      );
+    };
+
+    const createPointEntity = (point, size = 1.0, color = Color.RED, key) => {
+      const entities = [];
+      // Main point as a sphere
+      entities.push(
+        <Entity
+          key={key}
+          position={new Cartesian3(point.x, point.y, point.z)}
+          ellipsoid={{
+            radii: new Cartesian3(size, size, size), // Equal radii for a sphere 
+            material: color,
+          }}
+        />
+      );
+      return entities;
+    };
+
+    const createLineEntity = (m, width = 2, color = Color.YELLOW, key) => {
+      const start = new Cartesian3(m.camera.x, m.camera.y, m.camera.z);
+      const end = new Cartesian3(m.point.x, m.point.y, m.point.z);
+      return (
+        <Entity
+          key={key}
+          polyline={{
+            positions: [start, end],
+            width: width,
+            material: color,
+          }}
+        />
+      );
+    };
+
+    useEffect(() => {
+      let tileset;
+      let handler;
+      let cancelled = false;
+
+      // Wait until viewerRef.current.cesiumElement becomes available
+      const interval = setInterval(() => {
+        const viewer = viewerRef.current?.cesiumElement;
+        if (!viewer) return;
+
+        clearInterval(interval);
+
+        // Load a tileset
+        if (tilesetRef.current) {
+          viewer.scene.primitives.remove(tilesetRef.current);
+          tilesetRef.current = null;
+        }
+
+        if (!tilesetUrl) {
+          return;
+        }
+
+        Cesium.Cesium3DTileset.fromUrl(tilesetUrl)
+          .then((tileset) => {
+            if (cancelled) {
+              return;
+            }
+            // Enable gaussian splat rendering for KHR_gaussian_splatting tiles.
+            tileset.enableShowGaussianSplatting = true;
+            tileset.showGaussianSplatting = true;
+            // for red small object
+            offsetTilesetHeight(tileset, offsetHeight);
+            /*const lon = -83.02337;
+            const lat = 40.01608;
+            const height = 10.0;
+            const R = new Cesium.Matrix3(
+              0.940820, 0.223526, -0.254742,
+              0.338449, -0.658695,  0.671991,
+            -0.017590, -0.718440, -0.695366
+            );
+
+            // 1. ENU placement at given lon/lat/height
+            const origin = Cesium.Cartesian3.fromDegrees(lon, lat, height);
+            const enu = Cesium.Transforms.eastNorthUpToFixedFrame(origin);
+
+            // 2. Rotation from 3x3 matrix
+            const rotationMatrix4 = Cesium.Matrix4.fromRotationTranslation(R);
+
+            // 3. Scaling matrix
+            const scaleMatrix = Cesium.Matrix4.fromScale(
+              new Cesium.Cartesian3(1.0, 1.0, 1.0)
+            );
+
+            // 4. Combine: modelMatrix = ENU * Rotation * Scale
+            let finalMatrix = Cesium.Matrix4.multiply(enu, rotationMatrix4, new Cesium.Matrix4());
+            finalMatrix = Cesium.Matrix4.multiply(finalMatrix, scaleMatrix, finalMatrix);
+            tileset.modelMatrix = finalMatrix;*/
+
+            viewer.scene.primitives.add(tileset);
+            viewer.zoomTo(tileset);
+            tilesetRef.current = tileset;
+          })
+          .catch((error) => {
+            console.error("Error loading tileset:", error);
+          });
+        // Set up mouse event handler
+        handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
+
+        handler.setInputAction((click) => {
+          if (currentModeRef.current === "measure") {
+            const cartesian = viewer.camera.pickEllipsoid(
+              click.position,
+              viewer.scene.globe.ellipsoid,
+            );
+            if (cartesian) {
+              addMeausure(viewer.camera.positionWC, cartesian);
+            }
+          } else {
+          }
+        }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+
+        handler.setInputAction((movement) => {
+          /*const cartesian = viewer.camera.pickEllipsoid(
+          movement.endPosition,
+          viewer.scene.globe.ellipsoid
+        );
+        if (cartesian) {
+          // Example: show coordinates or highlight
+        }*/
+        }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
+      }, 200); // check every 200 ms until viewer is ready
+
+      // Cleanup
+      return () => {
+        cancelled = true;
+        clearInterval(interval);
+        if (handler) handler.destroy();
+        const viewer = viewerRef.current?.cesiumElement;
+        if (viewer && tileset) viewer.scene.primitives.remove(tileset);
+        if (viewer && tilesetRef.current) {
+          viewer.scene.primitives.remove(tilesetRef.current);
+          tilesetRef.current = null;
+        }
+      };
+    }, [tilesetUrl, offsetHeight]);
+
+    return (
+      <Viewer ref={viewerRef} full infoBox={false} selectionIndicator={false}>
+        {points.map((pt) =>
+          createCovarianceEntity(pt, 0.2, Color.BLUE.withAlpha(0.5), "point_" + pt.id, selectedPoint === pt.id),
+        )}
+        {measurements.map((m) =>
+          createLineEntity(m, 2, Color.YELLOW.withAlpha(0.5), "line_" + m.id),
+        )}
+      </Viewer>
+    );
+  },
+);
+
+export default CesiumViewer;

client/src/components/MeasurePanel.jsx

@@ -0,0 +1,361 @@
+import React, { useEffect, useState } from "react";
+import {
+  Card,
+  CardContent,
+  Typography,
+  Button,
+  List,
+  ListItemButton,
+  ListItemText,
+  Divider,
+  Stack,
+  FormControl,
+  InputLabel,
+  Select,
+  MenuItem,
+  TextField,
+  Dialog,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+} from "@mui/material";
+import DownloadIcon from "@mui/icons-material/Download";
+import DeleteIcon from "@mui/icons-material/Delete";
+import EditIcon from "@mui/icons-material/Edit";
+
+const DEFAULT_CUSTOM_MODEL = {
+  bucket: import.meta.env.VITE_S3_BUCKET || "ddy-first-bucket",
+  prefix: "data/3dtiles",
+  tileset: "custom/tileset.json",
+  offsetHeight: 0,
+};
+
+const DEFAULT_URL_MODEL = {
+  tilesetUrl: "",
+  offsetHeight: 0,
+};
+
+export default function MeasurePanel({
+  points,
+  onSelectPoint,
+  onDeletePoint,
+  onToggleMeasure,
+  measuring,
+  offsetHeight,
+  models,
+  selectedModelId,
+  customModel,
+  urlModel,
+  onModelChange,
+  onSaveCustomModel,
+  onSaveUrlModel,
+  onOffsetHeightChange,
+  onEditModel,
+}) {
+  const [selectedIndex, setSelectedIndex] = useState(null);
+  const [customDialogOpen, setCustomDialogOpen] = useState(false);
+  const [draftCustomModel, setDraftCustomModel] = useState(
+    customModel || DEFAULT_CUSTOM_MODEL
+  );
+  const [urlDialogOpen, setUrlDialogOpen] = useState(false);
+  const [draftUrlModel, setDraftUrlModel] = useState(
+    urlModel || DEFAULT_URL_MODEL
+  );
+
+  useEffect(() => {
+    if (!customDialogOpen) {
+      setDraftCustomModel(customModel || DEFAULT_CUSTOM_MODEL);
+    }
+  }, [customDialogOpen, customModel]);
+
+  useEffect(() => {
+    if (!urlDialogOpen) {
+      setDraftUrlModel(urlModel || DEFAULT_URL_MODEL);
+    }
+  }, [urlDialogOpen, urlModel]);
+
+  const handleSelect = (index) => {
+    setSelectedIndex(index);
+    if (onSelectPoint) onSelectPoint(points[index]);
+  };
+  const handleDeletePoint = () => {
+    if (onDeletePoint) onDeletePoint();
+  };
+  const handleExport = () => {
+    const dataStr =
+      "data:text/json;charset=utf-8," +
+      encodeURIComponent(JSON.stringify(points, null, 2));
+    const downloadAnchorNode = document.createElement("a");
+    downloadAnchorNode.setAttribute("href", dataStr);
+    downloadAnchorNode.setAttribute("download", "measured_points.json");
+    document.body.appendChild(downloadAnchorNode); // required for firefox
+    downloadAnchorNode.click();
+    downloadAnchorNode.remove();
+  };
+
+  const openCustomDialog = () => {
+    setDraftCustomModel(customModel || DEFAULT_CUSTOM_MODEL);
+    setCustomDialogOpen(true);
+  };
+
+  const openUrlDialog = () => {
+    setDraftUrlModel(urlModel || DEFAULT_URL_MODEL);
+    setUrlDialogOpen(true);
+  };
+
+  const handleModelChange = (event) => {
+    const nextModelId = event.target.value;
+    if (onModelChange) onModelChange(nextModelId);
+    if (nextModelId === "custom") {
+      openCustomDialog();
+    }
+    if (nextModelId === "url") {
+      openUrlDialog();
+    }
+  };
+
+  const handleCustomFieldChange = (field) => (event) => {
+    setDraftCustomModel((prev) => ({
+      ...prev,
+      [field]: event.target.value,
+    }));
+  };
+
+  const handleCustomSave = () => {
+    const nextOffset = Number(draftCustomModel.offsetHeight);
+    const payload = {
+      ...draftCustomModel,
+      offsetHeight: Number.isNaN(nextOffset) ? 0 : nextOffset,
+    };
+    if (onSaveCustomModel) onSaveCustomModel(payload);
+    setCustomDialogOpen(false);
+  };
+
+  const handleUrlFieldChange = (field) => (event) => {
+    setDraftUrlModel((prev) => ({
+      ...prev,
+      [field]: event.target.value,
+    }));
+  };
+
+  const handleUrlSave = () => {
+    const nextOffset = Number(draftUrlModel.offsetHeight);
+    const payload = {
+      ...draftUrlModel,
+      offsetHeight: Number.isNaN(nextOffset) ? 0 : nextOffset,
+    };
+    if (onSaveUrlModel) onSaveUrlModel(payload);
+    setUrlDialogOpen(false);
+  };
+
+  const handleCustomClose = () => {
+    setCustomDialogOpen(false);
+  };
+
+  const handleUrlClose = () => {
+    setUrlDialogOpen(false);
+  };
+
+  return (
+    <Card
+      sx={{
+        width: 400,
+        position: "absolute",
+        top: 20,
+        left: 20,
+        bgcolor: "background.paper",
+        boxShadow: 5,
+        borderRadius: 3,
+      }}
+    >
+      <CardContent>
+        <Typography variant="h6" gutterBottom>
+          3D Measurement
+        </Typography>
+
+        <Stack spacing={2} mt={2}>
+          <Stack direction="row" spacing={1}>
+            <FormControl size="small" fullWidth sx={{ flex: 1 }}>
+              <InputLabel id="model-select-label">Model</InputLabel>
+              <Select
+                labelId="model-select-label"
+                value={selectedModelId}
+                label="Model"
+                onChange={handleModelChange}
+              >
+                {models.map((model) => (
+                  <MenuItem key={model.id} value={model.id}>
+                    {model.name}
+                  </MenuItem>
+                ))}
+              </Select>
+            </FormControl>
+            {(selectedModelId === "custom" || selectedModelId === "url" || selectedModelId === "upload") && (
+              <Button
+                variant="outlined"
+                startIcon={<EditIcon />}
+                onClick={() => {
+                  if (selectedModelId === "custom") openCustomDialog();
+                  if (selectedModelId === "url") openUrlDialog();
+                  if (selectedModelId === "upload" && onEditModel) onEditModel();
+                }}
+              >
+                {selectedModelId === "upload" ? "Upload" : "Edit"}
+              </Button>
+            )}
+          </Stack>
+
+          <TextField
+            size="small"
+            label="Offset Height"
+            type="number"
+            value={offsetHeight}
+            onChange={(event) =>
+              onOffsetHeightChange && onOffsetHeightChange(event.target.value)
+            }
+            inputProps={{ step: 1 }}
+          />
+
+          <Stack direction="row" spacing={2}>
+            <Button
+              variant="contained"
+              color={measuring ? "error" : "primary"}
+              onClick={onToggleMeasure}
+            >
+              {measuring ? "End Measure" : "Start Measure"}
+            </Button>
+
+            <Button
+              variant="outlined"
+              color="primary"
+              startIcon={<DownloadIcon />}
+              onClick={() => handleExport()}
+              disabled={points.length === 0}
+            >
+              Export Points
+            </Button>
+          </Stack>
+
+          <Button
+            variant="outlined"
+            color="primary"
+            startIcon={<DeleteIcon />}
+            onClick={() => handleDeletePoint()}
+            disabled={points.length === 0}
+          >
+            Delete Point
+          </Button>
+        </Stack>
+
+        <Typography variant="subtitle1" sx={{ mb: 1, mt: 2 }}>
+          Measured Points
+        </Typography>
+
+        <List dense sx={{ maxHeight: 200, overflowY: "auto" }}>
+          {points.length === 0 && (
+            <Typography variant="body2" color="text.secondary" sx={{ px: 1 }}>
+              No points measured yet.
+            </Typography>
+          )}
+          {points.map((p, index) => (
+            <React.Fragment key={index}>
+              <ListItemButton
+                selected={selectedIndex === index}
+                onClick={() => handleSelect(index)}
+                sx={{
+                  borderRadius: 2,
+                  "&.Mui-selected": {
+                    bgcolor: "primary.light",
+                    color: "white",
+                    "&:hover": { bgcolor: "primary.main" },
+                  },
+                }}
+              >
+                <ListItemText
+                  primary={`Point ${p.id}`}
+                  secondary={`(${p.lat.toFixed(8)}, ${p.lon.toFixed(8)}, ${p.alt.toFixed(4)}) | Iz = ${p.accuracy.toFixed(3)} m`}
+                />
+              </ListItemButton>
+              {index < points.length - 1 && <Divider component="li" />}
+            </React.Fragment>
+          ))}
+        </List>
+      </CardContent>
+
+      <Dialog open={customDialogOpen} onClose={handleCustomClose} maxWidth="sm" fullWidth>
+        <DialogTitle>Custom S3 Model</DialogTitle>
+        <DialogContent>
+          <Stack spacing={2} mt={1}>
+            <TextField
+              size="small"
+              label="Bucket"
+              value={draftCustomModel.bucket}
+              onChange={handleCustomFieldChange("bucket")}
+              fullWidth
+            />
+            <TextField
+              size="small"
+              label="Prefix"
+              value={draftCustomModel.prefix}
+              onChange={handleCustomFieldChange("prefix")}
+              fullWidth
+            />
+            <TextField
+              size="small"
+              label="Tileset"
+              value={draftCustomModel.tileset}
+              onChange={handleCustomFieldChange("tileset")}
+              fullWidth
+            />
+            <TextField
+              size="small"
+              label="Offset Height"
+              type="number"
+              value={draftCustomModel.offsetHeight}
+              onChange={handleCustomFieldChange("offsetHeight")}
+              inputProps={{ step: 1 }}
+              fullWidth
+            />
+          </Stack>
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={handleCustomClose}>Cancel</Button>
+          <Button variant="contained" onClick={handleCustomSave}>
+            Save
+          </Button>
+        </DialogActions>
+      </Dialog>
+
+      <Dialog open={urlDialogOpen} onClose={handleUrlClose} maxWidth="sm" fullWidth>
+        <DialogTitle>URL Model</DialogTitle>
+        <DialogContent>
+          <Stack spacing={2} mt={1}>
+            <TextField
+              size="small"
+              label="Tileset URL"
+              placeholder="http://localhost:8000/tileset.json"
+              value={draftUrlModel.tilesetUrl}
+              onChange={handleUrlFieldChange("tilesetUrl")}
+              fullWidth
+            />
+            <TextField
+              size="small"
+              label="Offset Height"
+              type="number"
+              value={draftUrlModel.offsetHeight}
+              onChange={handleUrlFieldChange("offsetHeight")}
+              inputProps={{ step: 1 }}
+              fullWidth
+            />
+          </Stack>
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={handleUrlClose}>Cancel</Button>
+          <Button variant="contained" onClick={handleUrlSave}>
+            Save
+          </Button>
+        </DialogActions>
+      </Dialog>
+    </Card>
+  );
+}

client/src/index.css

@@ -0,0 +1,68 @@
+:root {
+  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

client/src/main.jsx

@@ -0,0 +1,11 @@
+import './cesiumSetup'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.jsx'
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

client/src/pages/Home.jsx

@@ -0,0 +1,357 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import CesiumViewer from "../components/CesiumViewer";
+import MeasurePanel from "../components/MeasurePanel";
+import { getDefaultBucket, validateAwsConfig, AWS_REGION } from "../utils/awsConfig";
+import {
+  Dialog,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+  Button,
+  TextField,
+  Stack,
+} from "@mui/material";
+
+// Models configured to use AWS Cognito authentication
+// No credentials are stored in code
+const BASE_MODELS = [
+  {
+    id: "small-object-1",
+    name: "Small Object 1",
+    tileset: "small_object_1/3dgs/tileset.json",
+    prefix: "data/3dtiles",
+    bucket: getDefaultBucket(),
+    offsetHeight: -130,
+  },
+  {
+    id: "small-object-2",
+    name: "Small Object 2",
+    tileset: "small_object_2/3dgs/tileset.json",
+    prefix: "data/3dtiles",
+    bucket: getDefaultBucket(),
+    offsetHeight: -130,
+  },
+  {
+    id: "wex-cc-3dgs",
+    name: "Wex CC 3DGS",
+    tileset: "wex_cc_3dgs/tileset.json",
+    prefix: "data/3dtiles",
+    bucket: getDefaultBucket(),
+    offsetHeight: -50,
+  },
+  {
+    id: "2dgs",
+    name: "2DGS",
+    tileset: "2dgs/tileset.json",
+    prefix: "data/3dtiles",
+    bucket: getDefaultBucket(),
+    offsetHeight: -200,
+  },
+];
+
+function buildTilesetUrl(model) {
+  if (!model.bucket) return "";
+
+  const tilesetPath = (model.tileset || "tileset.json").replace(/^\/+/, "");
+  const prefix = (model.prefix || "").replace(/\/+$/, "");
+  const s3Key = prefix ? `${prefix}/${tilesetPath}` : tilesetPath;
+
+  // Return placeholder - actual signed URL will be created asynchronously
+  return s3Key;
+}
+
+export default function Home() {
+  // AWS configuration validation
+  useEffect(() => {
+    if (!validateAwsConfig()) {
+      console.warn(
+        "AWS configuration incomplete. Check your .env file for required variables."
+      );
+    }
+  }, []);
+
+  const [customModel, setCustomModel] = useState({
+    bucket: getDefaultBucket(),
+    prefix: "data/3dtiles",
+    tileset: "custom/tileset.json",
+    offsetHeight: 0,
+  });
+  const [uploadedModel, setUploadedModel] = useState({
+    tilesetUrl: "",
+    offsetHeight: 0,
+  });
+  const [urlModel, setUrlModel] = useState({
+    tilesetUrl: "",
+    offsetHeight: 0,
+  });
+  const [uploadDialogOpen, setUploadDialogOpen] = useState(false);
+  const [uploadParams, setUploadParams] = useState({ lat: 0, lon: 0 });
+
+  const models = useMemo(
+    () => [
+      ...BASE_MODELS,
+      {
+        id: "custom",
+        name: "Custom S3 Model",
+      },
+      {
+        id: "url",
+        name: "URL Model",
+      },
+      {
+        id: "upload",
+        name: "Upload PLY/Splat",
+      },
+    ],
+    []
+  );
+
+  const [selectedModelId, setSelectedModelId] = useState(models[0].id);
+  const [previousModelId, setPreviousModelId] = useState(models[0].id);
+  const selectedModel = useMemo(() => {
+    if (selectedModelId === "custom") {
+      return { id: "custom", name: "Custom S3 Model", ...customModel };
+    }
+    if (selectedModelId === "url") {
+      return { id: "url", name: "URL Model", ...urlModel };
+    }
+    if (selectedModelId === "upload") {
+      return { id: "upload", name: "Uploaded Model", ...uploadedModel };
+    }
+    return (
+      BASE_MODELS.find((model) => model.id === selectedModelId) ||
+      BASE_MODELS[0]
+    );
+  }, [selectedModelId, customModel, urlModel, uploadedModel]);
+
+  const [offsetHeight, setOffsetHeight] = useState(
+    selectedModel.offsetHeight ?? 0
+  );
+
+  // Use direct unsigned S3 URL (bucket is publicly readable)
+  const [tilesetUrl, setTilesetUrl] = useState("");
+  const [isUploading, setIsUploading] = useState(false);
+  const fileInputRef = useRef(null);
+
+  useEffect(() => {
+    if (selectedModelId === "url") {
+      setTilesetUrl(urlModel.tilesetUrl || "");
+      return;
+    }
+    if (selectedModelId === "upload") {
+      setTilesetUrl(uploadedModel.tilesetUrl || "");
+      return;
+    }
+
+    const s3Key = buildTilesetUrl(selectedModel);
+    const directUrl = `https://${selectedModel.bucket}.s3.${AWS_REGION}.amazonaws.com/${s3Key}`;
+    setTilesetUrl(directUrl);
+  }, [selectedModel, selectedModelId, urlModel.tilesetUrl, uploadedModel.tilesetUrl]);
+
+  const [points, setPoints] = useState([]);
+  const [isMeasuring, setIsMeasuring] = useState(false);
+  const cesiumRef = useRef(null);
+  const maxPointId = useRef(0);
+  const [selectedPoint, setSelectedPoint] = useState(0);
+
+  const handleAddPoint = (point) => {
+    maxPointId.current += 1;
+    console.log("New 3D point added:", point);
+    setPoints((prev) => [...prev, { ...point, id: maxPointId.current }]);
+  };
+
+  const handleMeasureClick = () => {
+    if (!cesiumRef.current) return;
+    if (isMeasuring) {
+      cesiumRef.current.endMeasure();
+      setIsMeasuring(false);
+    } else {
+      cesiumRef.current.setMode("measure");
+      setIsMeasuring(true);
+    }
+  };
+  const handleSelectPoint = (point) => {
+    if (!cesiumRef.current) return;
+    setSelectedPoint(point.id);
+    console.log("Selected point for inspection:", point);
+  };
+  const handleDeletePoint = () => {
+    if (!cesiumRef.current) return;
+    if (selectedPoint === 0) return;
+    setPoints((prev) => prev.filter((pt) => pt.id !== selectedPoint));
+    setSelectedPoint(0);
+  };
+
+  const handleModelChange = (modelId) => {
+    if (modelId !== selectedModelId) {
+      setPreviousModelId(selectedModelId);
+    }
+    if (modelId === "upload") {
+      setUploadDialogOpen(true);
+    }
+    setSelectedModelId(modelId);
+  };
+
+  const handleCustomModelSave = (model) => {
+    const nextOffset = Number(model.offsetHeight);
+    const normalizedModel = {
+      ...model,
+      offsetHeight: Number.isNaN(nextOffset) ? 0 : nextOffset,
+    };
+    setCustomModel(normalizedModel);
+    setSelectedModelId("custom");
+  };
+
+  const handleUrlModelSave = (model) => {
+    const nextOffset = Number(model.offsetHeight);
+    const normalizedModel = {
+      ...model,
+      offsetHeight: Number.isNaN(nextOffset) ? 0 : nextOffset,
+    };
+    setUrlModel(normalizedModel);
+    setSelectedModelId("url");
+  };
+
+  const handleOffsetHeightChange = (value) => {
+    const nextValue = Number(value);
+    if (!Number.isNaN(nextValue)) {
+      setOffsetHeight(nextValue);
+      if (selectedModelId === "custom") {
+        setCustomModel((prev) => ({ ...prev, offsetHeight: nextValue }));
+      }
+      if (selectedModelId === "url") {
+        setUrlModel((prev) => ({ ...prev, offsetHeight: nextValue }));
+      }
+      if (selectedModelId === "upload") {
+        setUploadedModel((prev) => ({ ...prev, offsetHeight: nextValue }));
+      }
+    }
+  };
+
+  useEffect(() => {
+    setOffsetHeight(selectedModel.offsetHeight ?? 0);
+  }, [selectedModelId, selectedModel.offsetHeight]);
+
+  const handleFileUpload = async (event) => {
+    const file = event.target.files?.[0];
+    if (!file) return;
+
+    setIsUploading(true);
+    const formData = new FormData();
+    formData.append("file", file);
+    formData.append("lat", uploadParams.lat);
+    formData.append("lon", uploadParams.lon);
+
+    try {
+      const response = await fetch("/api/upload", {
+        method: "POST",
+        body: formData,
+      });
+
+      if (!response.ok) {
+        const err = await response.json();
+        throw new Error(err.detail || "Upload failed");
+      }
+
+      const data = await response.json();
+      setUploadedModel((prev) => ({
+        ...prev,
+        tilesetUrl: data.tilesetUrl,
+        offsetHeight: 0,
+      }));
+      setOffsetHeight(0);
+    } catch (error) {
+      console.error("Upload error:", error);
+      alert("Failed to upload/convert model: " + error.message);
+    } finally {
+      setIsUploading(false);
+    }
+  };
+
+  return (
+    <div style={{ height: "100vh", width: "100vw", position: "relative" }}>
+      <input
+        type="file"
+        ref={fileInputRef}
+        style={{ display: "none" }}
+        accept=".ply,.splat"
+        onChange={handleFileUpload}
+      />
+      {isUploading && (
+        <div style={{
+          position: "absolute", top: 0, left: 0, right: 0, bottom: 0,
+          backgroundColor: "rgba(0,0,0,0.7)", color: "white", zIndex: 9999,
+          display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center"
+        }}>
+          <h2>Converting Model...</h2>
+          <p>Please wait while we process your file.</p>
+        </div>
+      )}
+      {/* Cesium Viewer */}
+      <CesiumViewer
+        ref={cesiumRef}
+        tilesetUrl={tilesetUrl}
+        points={points}
+        onAddPoint={handleAddPoint}
+        offsetHeight={offsetHeight}
+        selectedPoint={selectedPoint}
+      />
+
+      {/* MUI Overlay */}
+      <MeasurePanel
+        points={points}
+        measuring={isMeasuring}
+        offsetHeight={offsetHeight}
+        models={models}
+        selectedModelId={selectedModelId}
+        customModel={customModel}
+        urlModel={urlModel}
+        onModelChange={handleModelChange}
+        onSaveCustomModel={handleCustomModelSave}
+        onSaveUrlModel={handleUrlModelSave}
+        onOffsetHeightChange={handleOffsetHeightChange}
+        onToggleMeasure={handleMeasureClick}
+        onSelectPoint={handleSelectPoint}
+        onDeletePoint={handleDeletePoint}
+        onEditModel={() => setUploadDialogOpen(true)}
+      />
+
+      {/* Upload Dialog */}
+      <Dialog open={uploadDialogOpen} onClose={() => setUploadDialogOpen(false)}>
+        <DialogTitle>Upload Model</DialogTitle>
+        <DialogContent>
+          <Stack spacing={2} mt={1}>
+            <TextField
+              label="Latitude"
+              type="number"
+              value={uploadParams.lat}
+              onChange={(e) => setUploadParams(prev => ({ ...prev, lat: e.target.value }))}
+              fullWidth
+            />
+            <TextField
+              label="Longitude"
+              type="number"
+              value={uploadParams.lon}
+              onChange={(e) => setUploadParams(prev => ({ ...prev, lon: e.target.value }))}
+              fullWidth
+            />
+          </Stack>
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={() => {
+            setUploadDialogOpen(false);
+            if (!uploadedModel.tilesetUrl) {
+              setSelectedModelId(previousModelId);
+            }
+          }}>Cancel</Button>
+          <Button variant="contained" onClick={() => {
+            setUploadDialogOpen(false);
+            fileInputRef.current?.click();
+          }}>
+            Select File & Upload
+          </Button>
+        </DialogActions>
+      </Dialog>
+    </div>
+  );
+}

client/src/pages/VisitLog.css

@@ -0,0 +1,329 @@
+@import url("https://fonts.googleapis.com/css2?family=Fraunces:wght@500;700&family=Space+Grotesk:wght@400;500;600&display=swap");
+
+:root {
+  --visit-bg: #f4f1ec;
+  --visit-ink: #1c1b19;
+  --visit-muted: #6b6357;
+  --visit-accent: #c9743a;
+  --visit-card: #fffaf3;
+  --visit-shadow: rgba(30, 24, 16, 0.12);
+}
+
+.visit-log-body #root {
+  max-width: none;
+  width: 100%;
+  padding: 0;
+}
+
+.visit-log-body {
+  margin: 0;
+}
+
+.visit-log-page {
+  min-height: 100vh;
+  padding: 48px 20px 80px;
+  background: radial-gradient(circle at top, #fff6e7 0%, var(--visit-bg) 60%);
+  color: var(--visit-ink);
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+}
+
+.visit-log-header {
+  width: 100%;
+  margin: 0 0 32px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 24px;
+  align-items: flex-end;
+  justify-content: space-between;
+}
+
+.visit-log-header h1 {
+  font-family: "Fraunces", "Times New Roman", serif;
+  font-size: clamp(2rem, 4vw, 3rem);
+  margin: 6px 0 8px;
+  letter-spacing: -0.02em;
+}
+
+.visit-log-eyebrow {
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  font-size: 0.7rem;
+  color: var(--visit-accent);
+  margin: 0;
+}
+
+.visit-log-subtitle {
+  max-width: 520px;
+  color: var(--visit-muted);
+  margin: 0;
+}
+
+.visit-log-back {
+  text-decoration: none;
+  color: var(--visit-ink);
+  border: 1px solid var(--visit-ink);
+  padding: 10px 18px;
+  border-radius: 999px;
+  font-size: 0.9rem;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.visit-log-back:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 18px var(--visit-shadow);
+}
+
+.visit-log-card {
+  width: 100%;
+  margin: 0 0 32px;
+  background: var(--visit-card);
+  padding: 24px;
+  border-radius: 20px;
+  box-shadow: 0 16px 30px var(--visit-shadow);
+  display: grid;
+  gap: 18px;
+}
+
+.visit-log-form {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: 1fr auto;
+  align-items: end;
+}
+
+.visit-log-form label {
+  display: block;
+  font-size: 0.8rem;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+  color: var(--visit-muted);
+  margin-bottom: 8px;
+}
+
+.visit-log-form input {
+  width: 100%;
+  padding: 12px 14px;
+  border-radius: 12px;
+  border: 1px solid #d7c9b3;
+  background: #fff;
+  font-size: 1rem;
+}
+
+.visit-log-form button {
+  padding: 12px 22px;
+  border-radius: 999px;
+  border: none;
+  background: var(--visit-ink);
+  color: #fff7ee;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.visit-log-form button:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.visit-log-stats {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+}
+
+.visit-log-stats div {
+  padding: 16px;
+  border-radius: 16px;
+  background: rgba(201, 116, 58, 0.08);
+}
+
+.visit-log-stats span {
+  display: block;
+  color: var(--visit-muted);
+  font-size: 0.85rem;
+}
+
+.visit-log-stats strong {
+  font-size: 1.2rem;
+}
+
+.visit-log-error {
+  width: 100%;
+  margin: 0 0 24px;
+  padding: 12px 16px;
+  border-radius: 12px;
+  background: #ffe2d6;
+  color: #8b2c10;
+}
+
+.visit-log-grid {
+  width: 100%;
+  margin: 0;
+  display: grid;
+  gap: 18px;
+}
+
+.visit-log-entry {
+  background: #fff;
+  border-radius: 18px;
+  padding: 20px 22px;
+  box-shadow: 0 10px 22px rgba(30, 24, 16, 0.08);
+  border: 1px solid #f0e2cd;
+}
+
+.visit-log-entry-header {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  justify-content: space-between;
+  align-items: baseline;
+}
+
+.visit-log-entry-header h2 {
+  font-size: 1.1rem;
+  margin: 0;
+  font-weight: 600;
+}
+
+.visit-log-entry-path {
+  font-size: 0.85rem;
+  color: var(--visit-muted);
+}
+
+.visit-log-entry-body {
+  margin-top: 16px;
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+}
+
+.visit-log-entry-body span {
+  display: block;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.14em;
+  color: var(--visit-muted);
+  margin-bottom: 6px;
+}
+
+.visit-log-entry-body strong {
+  font-weight: 600;
+}
+
+.visit-log-empty {
+  padding: 24px;
+  border-radius: 16px;
+  background: #fff4e4;
+  text-align: center;
+  color: var(--visit-muted);
+}
+
+.visit-log-layout {
+  width: 100%;
+  margin: 0 0 32px;
+  display: grid;
+  grid-template-columns: minmax(240px, 320px) 1fr;
+  gap: 20px;
+}
+
+.visit-log-sidebar {
+  background: #fffaf3;
+  border-radius: 18px;
+  padding: 18px;
+  box-shadow: 0 12px 22px rgba(30, 24, 16, 0.08);
+  border: 1px solid #f0e2cd;
+  display: grid;
+  gap: 12px;
+  max-height: 520px;
+  overflow: hidden;
+}
+
+.visit-log-sidebar-header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+}
+
+.visit-log-sidebar-header h2 {
+  margin: 0;
+  font-size: 1.1rem;
+}
+
+.visit-log-sidebar-header span {
+  font-size: 0.85rem;
+  color: var(--visit-muted);
+}
+
+.visit-log-visitor-list {
+  overflow-y: auto;
+  padding-right: 6px;
+  display: grid;
+  gap: 10px;
+}
+
+.visit-log-visitor {
+  text-align: left;
+  border: 1px solid #eddac2;
+  border-radius: 14px;
+  padding: 12px;
+  background: #fff;
+  display: grid;
+  gap: 6px;
+  cursor: pointer;
+  transition: border 0.2s ease, box-shadow 0.2s ease, transform 0.2s ease;
+}
+
+.visit-log-visitor strong {
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+
+.visit-log-visitor span {
+  font-size: 0.8rem;
+  color: var(--visit-muted);
+}
+
+.visit-log-visitor:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 10px 18px rgba(30, 24, 16, 0.08);
+}
+
+.visit-log-visitor--active {
+  border-color: var(--visit-accent);
+  box-shadow: 0 10px 20px rgba(201, 116, 58, 0.18);
+}
+
+.visit-log-map-panel {
+  background: #fff;
+  border-radius: 18px;
+  padding: 16px;
+  box-shadow: 0 12px 22px rgba(30, 24, 16, 0.08);
+  border: 1px solid #f0e2cd;
+  display: grid;
+  gap: 12px;
+}
+
+.visit-log-map {
+  width: 100%;
+  min-height: 420px;
+  border-radius: 14px;
+  overflow: hidden;
+}
+
+.visit-log-map-note {
+  font-size: 0.85rem;
+  color: var(--visit-muted);
+}
+
+@media (max-width: 720px) {
+  .visit-log-form {
+    grid-template-columns: 1fr;
+  }
+
+  .visit-log-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .visit-log-sidebar {
+    max-height: none;
+  }
+}

client/src/pages/VisitLog.jsx

@@ -0,0 +1,371 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import "./VisitLog.css";
+
+const EMPTY_STATE = [];
+
+function formatTimestamp(value) {
+  if (!value) return "Unknown time";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString();
+}
+
+function formatLocation(location) {
+  if (!location || typeof location.lat !== "number") {
+    return "Unavailable";
+  }
+  const lat = location.lat.toFixed(4);
+  const lon = location.lon.toFixed(4);
+  const accuracy = location.accuracyMeters
+    ? `${Math.round(location.accuracyMeters)} m`
+    : "Unknown";
+  return `${lat}, ${lon} (+/-${accuracy})`;
+}
+
+function loadGoogleMaps(apiKey) {
+  if (typeof window === "undefined") {
+    return Promise.reject(new Error("Window not available"));
+  }
+  if (window.google && window.google.maps) {
+    return Promise.resolve(window.google);
+  }
+
+  return new Promise((resolve, reject) => {
+    const existing = document.querySelector("script[data-google-maps]");
+    if (existing) {
+      existing.addEventListener("load", () => resolve(window.google));
+      existing.addEventListener("error", () =>
+        reject(new Error("Failed to load Google Maps"))
+      );
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}`;
+    script.async = true;
+    script.defer = true;
+    script.dataset.googleMaps = "true";
+    script.addEventListener("load", () => resolve(window.google));
+    script.addEventListener("error", () =>
+      reject(new Error("Failed to load Google Maps"))
+    );
+    document.head.appendChild(script);
+  });
+}
+
+export default function VisitLog() {
+  const [visitorId, setVisitorId] = useState("");
+  const [selectedVisitorId, setSelectedVisitorId] = useState("");
+  const [visits, setVisits] = useState(EMPTY_STATE);
+  const [visitors, setVisitors] = useState(EMPTY_STATE);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+  const [mapError, setMapError] = useState("");
+  const mapContainerRef = useRef(null);
+  const mapRef = useRef(null);
+  const markersRef = useRef([]);
+  const pendingFocusRef = useRef("");
+  const apiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
+
+  const visitCount = visits.length;
+  const lastSeen = useMemo(() => {
+    if (!visitCount) return "No visits yet";
+    return formatTimestamp(visits[0].ts);
+  }, [visitCount, visits]);
+
+  const fetchVisits = async (targetName) => {
+    if (!targetName) return;
+    setLoading(true);
+    setError("");
+    try {
+      const response = await fetch(
+        `/api/visits?username=${encodeURIComponent(targetName)}`
+      );
+      const payload = await response.json();
+      if (!response.ok) {
+        throw new Error(payload.message || "Failed to load visits");
+      }
+      setVisits(Array.isArray(payload.visits) ? payload.visits : []);
+    } catch (err) {
+      setError(err.message || "Failed to load visits");
+      setVisits(EMPTY_STATE);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const fetchVisitors = async () => {
+    try {
+      const response = await fetch("/api/visitors");
+      const payload = await response.json();
+      if (!response.ok) {
+        throw new Error(payload.message || "Failed to load visitors");
+      }
+      setVisitors(Array.isArray(payload.visitors) ? payload.visitors : []);
+    } catch (err) {
+      setMapError(err.message || "Failed to load visitors");
+    }
+  };
+
+  const handleSelectVisitor = (targetName) => {
+    if (!targetName) return;
+    setVisitorId(targetName);
+    setSelectedVisitorId(targetName);
+    fetchVisits(targetName);
+    pendingFocusRef.current = targetName;
+    focusMapOnVisitor(targetName);
+  };
+
+  const focusMapOnVisitor = (targetName) => {
+    if (!mapRef.current || !window.google || !targetName) {
+      return;
+    }
+    const match = visitors.find(
+      (visitor) =>
+        visitor.username === targetName || visitor.visitorId === targetName
+    );
+    const location = match?.location;
+    if (!location || typeof location.lat !== "number") {
+      return;
+    }
+    const position = { lat: location.lat, lng: location.lon };
+    mapRef.current.panTo(position);
+    mapRef.current.setZoom(8);
+  };
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const fromQuery = params.get("username") || "";
+    if (fromQuery) {
+      handleSelectVisitor(fromQuery);
+    }
+  }, []);
+
+  const handleSubmit = (event) => {
+    event.preventDefault();
+    handleSelectVisitor(visitorId.trim());
+  };
+
+  useEffect(() => {
+    document.body.classList.add("visit-log-body");
+    return () => {
+      document.body.classList.remove("visit-log-body");
+    };
+  }, []);
+
+  useEffect(() => {
+    fetchVisitors();
+  }, []);
+
+  useEffect(() => {
+    if (!apiKey) {
+      setMapError("Missing Google Maps API key.");
+      return;
+    }
+
+    let cancelled = false;
+    loadGoogleMaps(apiKey)
+      .then(() => {
+        if (cancelled) return;
+        if (!mapRef.current && mapContainerRef.current) {
+          mapRef.current = new window.google.maps.Map(
+            mapContainerRef.current,
+            {
+              center: { lat: 20, lng: 0 },
+              zoom: 2,
+              mapTypeControl: false,
+              streetViewControl: false,
+              fullscreenControl: false,
+            }
+          );
+        }
+        if (pendingFocusRef.current) {
+          focusMapOnVisitor(pendingFocusRef.current);
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setMapError(err.message || "Failed to load Google Maps");
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [apiKey]);
+
+  useEffect(() => {
+    if (!mapRef.current || !window.google) {
+      return;
+    }
+
+    markersRef.current.forEach((marker) => marker.setMap(null));
+    markersRef.current = [];
+
+    const bounds = new window.google.maps.LatLngBounds();
+    let hasMarker = false;
+
+    visitors.forEach((visitor) => {
+      const location = visitor.location;
+      if (!location || typeof location.lat !== "number") {
+        return;
+      }
+      const position = { lat: location.lat, lng: location.lon };
+      const marker = new window.google.maps.Marker({
+        position,
+        map: mapRef.current,
+        title: visitor.visitorId,
+      });
+      marker.addListener("click", () => handleSelectVisitor(visitor.visitorId));
+      markersRef.current.push(marker);
+      bounds.extend(position);
+      hasMarker = true;
+    });
+
+    if (hasMarker) {
+      mapRef.current.fitBounds(bounds);
+    } else {
+      mapRef.current.setCenter({ lat: 20, lng: 0 });
+      mapRef.current.setZoom(2);
+    }
+    if (pendingFocusRef.current) {
+      focusMapOnVisitor(pendingFocusRef.current);
+    }
+  }, [visitors]);
+
+  useEffect(() => {
+    if (!selectedVisitorId) {
+      return;
+    }
+    focusMapOnVisitor(selectedVisitorId);
+  }, [selectedVisitorId, visitors]);
+
+  return (
+    <div className="visit-log-page">
+      <header className="visit-log-header">
+        <div>
+          <p className="visit-log-eyebrow">Visitor Insights</p>
+          <h1>Visit Timeline</h1>
+          <p className="visit-log-subtitle">
+            Track visits for a specific visitor and review model selections with
+            coarse location context.
+          </p>
+        </div>
+        <a className="visit-log-back" href="/">
+          Back to 3D Viewer
+        </a>
+      </header>
+
+      <section className="visit-log-card">
+        <form className="visit-log-form" onSubmit={handleSubmit}>
+          <div>
+            <label htmlFor="visitorId">Visitor ID</label>
+            <input
+              id="visitorId"
+              value={visitorId}
+              onChange={(event) => setVisitorId(event.target.value)}
+              placeholder="v_..."
+            />
+          </div>
+          <button type="submit" disabled={!visitorId || loading}>
+            {loading ? "Loading..." : "Load Visits"}
+          </button>
+        </form>
+
+        <div className="visit-log-stats">
+          <div>
+            <span>Total Visits</span>
+            <strong>{visitCount}</strong>
+          </div>
+          <div>
+            <span>Last Seen</span>
+            <strong>{lastSeen}</strong>
+          </div>
+        </div>
+      </section>
+
+      {error && <p className="visit-log-error">{error}</p>}
+      {mapError && <p className="visit-log-error">{mapError}</p>}
+
+      <section className="visit-log-layout">
+        <aside className="visit-log-sidebar">
+          <div className="visit-log-sidebar-header">
+            <h2>Visitors</h2>
+            <span>{visitors.length} total</span>
+          </div>
+          <div className="visit-log-visitor-list">
+            {visitors.length === 0 && (
+              <p className="visit-log-empty">
+                No visitors found. Make sure the visit log has data.
+              </p>
+            )}
+            {visitors.map((visitor) => (
+              <button
+                key={visitor.visitorId}
+                className={
+                  visitor.username === selectedVisitorId
+                    ? "visit-log-visitor visit-log-visitor--active"
+                    : "visit-log-visitor"
+                }
+                type="button"
+                onClick={() => handleSelectVisitor(visitor.username || visitor.visitorId)}
+              >
+                <strong>{visitor.username || visitor.visitorId}</strong>
+                <span>{formatTimestamp(visitor.lastSeen)}</span>
+              </button>
+            ))}
+          </div>
+        </aside>
+
+        <div className="visit-log-map-panel">
+          <div className="visit-log-map" ref={mapContainerRef} />
+          <div className="visit-log-map-note">
+            Click a marker or visitor to view their history.
+          </div>
+        </div>
+      </section>
+
+      <section className="visit-log-grid">
+        {visitCount === 0 && !loading && !error && (
+          <div className="visit-log-empty">
+            No visits yet. Enter a visitor ID to view activity.
+          </div>
+        )}
+        {visits.map((visit, index) => (
+          <article className="visit-log-entry" key={`${visit.ts}-${index}`}>
+            <div className="visit-log-entry-header">
+              <h2>{formatTimestamp(visit.ts)}</h2>
+              <span className="visit-log-entry-path">{visit.path || "/"}</span>
+            </div>
+            <div className="visit-log-entry-body">
+              <div>
+                <span>User</span>
+                <strong>{visit.username || visit.visitorId || "Unknown"}</strong>
+              </div>
+              <div>
+                <span>Model</span>
+                <strong>{visit.model?.name || visit.model?.id || "Unknown"}</strong>
+              </div>
+              <div>
+                <span>Tileset</span>
+                <strong>{visit.model?.tileset || "Unknown"}</strong>
+              </div>
+              <div>
+                <span>Offset Height</span>
+                <strong>
+                  {typeof visit.model?.offsetHeight === "number"
+                    ? visit.model.offsetHeight
+                    : "Unknown"}
+                </strong>
+              </div>
+              <div>
+                <span>Coarse Location</span>
+                <strong>{formatLocation(visit.location)}</strong>
+              </div>
+            </div>
+          </article>
+        ))}
+      </section>
+    </div>
+  );
+}

client/src/utils/awsConfig.js

@@ -0,0 +1,160 @@
+/**
+ * AWS Configuration for Cognito-based S3 access
+ * 
+ * This module handles AWS credentials through Cognito Identity Provider.
+ * No AWS credentials are stored in code or exposed to the client.
+ * 
+ * Environment Variables Required:
+ * - VITE_AWS_REGION: AWS region (e.g., "us-east-2")
+ * - VITE_AWS_COGNITO_IDENTITY_POOL_ID: Cognito Identity Pool ID (e.g., "us-east-2:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
+ * - VITE_S3_BUCKET: Default S3 bucket name (e.g., "ddy-first-bucket")
+ */
+
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { fromCognitoIdentityPool } from "@aws-sdk/credential-provider-cognito-identity";
+import { CognitoIdentityClient } from "@aws-sdk/client-cognito-identity";
+
+export const AWS_REGION = "us-east-2";
+// Cognito pool ID is safe to embed in client code (not a secret)
+export const COGNITO_IDENTITY_POOL_ID = "us-east-2:1387102d-5a87-4742-8a69-1baa70f37984";
+export const DEFAULT_BUCKET = "ddy-first-bucket";
+
+/**
+ * Initialize S3 client with Cognito credentials
+ * Uses unauthenticated Cognito Identity pool for public S3 access
+ */
+export function getS3Client() {
+  const credentialsProvider = fromCognitoIdentityPool({
+    client: new CognitoIdentityClient({ region: AWS_REGION }),
+    identityPoolId: COGNITO_IDENTITY_POOL_ID,
+  });
+
+  return new S3Client({
+    region: AWS_REGION,
+    credentials: credentialsProvider,
+  });
+}
+
+/**
+ * Get S3 object as text (for JSON tilesets, metadata, etc.)
+ */
+export async function getS3ObjectAsText(bucket, key) {
+  const s3Client = getS3Client();
+  if (!s3Client) {
+    throw new Error("S3 client not initialized");
+  }
+
+  try {
+    const command = new GetObjectCommand({
+      Bucket: bucket,
+      Key: key,
+    });
+
+    const response = await s3Client.send(command);
+    const text = await response.Body.transformToString();
+    return text;
+  } catch (error) {
+    console.error(`Failed to fetch S3 object s3://${bucket}/${key}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Get S3 object as JSON
+ */
+export async function getS3ObjectAsJson(bucket, key) {
+  const text = await getS3ObjectAsText(bucket, key);
+  return JSON.parse(text);
+}
+
+/**
+ * Build a direct S3 URL for tile assets
+ * Note: This URL requires proper CORS configuration on S3 bucket
+ * or the bucket must be public with proper authentication
+ */
+export function buildS3Url(bucket, key) {
+  return `https://${bucket}.s3.${AWS_REGION}.amazonaws.com/${key}`;
+}
+
+/**
+ * Rewrite URLs in a tileset JSON to use proper S3 paths
+ * Handles both relative and absolute URLs
+ */
+export function rewriteTilesetUrls(tilesetJson, bucket, basePath) {
+  const rewrite = (obj) => {
+    if (!obj || typeof obj !== "object") return;
+
+    if (Array.isArray(obj)) {
+      obj.forEach(rewrite);
+      return;
+    }
+
+    Object.keys(obj).forEach((key) => {
+      const value = obj[key];
+
+      // Rewrite uri/url fields to point to S3
+      if ((key === "uri" || key === "url") && typeof value === "string") {
+        // Skip external URLs
+        if (value.startsWith("http://") || value.startsWith("https://")) {
+          return;
+        }
+
+        // Skip data URLs
+        if (value.startsWith("data:")) {
+          return;
+        }
+
+        // Build S3 URL for relative paths
+        const relativePath = value.startsWith("/") ? value.slice(1) : value;
+        const s3Key = basePath
+          ? `${basePath}/${relativePath}`.replace(/\/+/g, "/")
+          : relativePath;
+
+        obj[key] = buildS3Url(bucket, s3Key);
+      }
+
+      // Recursively rewrite nested objects
+      if (typeof value === "object") {
+        rewrite(value);
+      }
+    });
+  };
+
+  rewrite(tilesetJson);
+  return tilesetJson;
+}
+
+/**
+ * Load a tileset JSON file from S3 and rewrite its URLs
+ */
+export async function loadTilesetFromS3(bucket, tilesetPath, basePath) {
+  try {
+    const tilesetJson = await getS3ObjectAsJson(bucket, tilesetPath);
+    return rewriteTilesetUrls(tilesetJson, bucket, basePath);
+  } catch (error) {
+    console.error(`Failed to load tileset from S3:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Get default S3 bucket name
+ */
+export function getDefaultBucket() {
+  return DEFAULT_BUCKET;
+}
+
+/**
+ * Get AWS region
+ */
+export function getAwsRegion() {
+  return AWS_REGION;
+}
+
+/**
+ * Validate AWS configuration
+ */
+export function validateAwsConfig() {
+  // Configuration is hardcoded, always valid
+  return true;
+}

client/src/utils/visitorTracking.js

@@ -0,0 +1,194 @@
+const VISITOR_ID_KEY = "gda.visitorId";
+const VISITOR_HISTORY_KEY = "gda.visitorHistory";
+const VISITOR_COOKIE = "gda_vid";
+const SESSION_MARK_KEY = "gda.visitRecorded";
+const LOCATION_CACHE_KEY = "gda.coarseLocation";
+
+function generateVisitorId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+
+  const random = Math.random().toString(36).slice(2);
+  const time = Date.now().toString(36);
+  return `v_${time}_${random}`;
+}
+
+function getOrCreateVisitorId() {
+  try {
+    const existing = localStorage.getItem(VISITOR_ID_KEY);
+    if (existing) {
+      return existing;
+    }
+
+    const id = generateVisitorId();
+    localStorage.setItem(VISITOR_ID_KEY, id);
+    return id;
+  } catch {
+    return generateVisitorId();
+  }
+}
+
+function markCookie(visitorId) {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  document.cookie = `${VISITOR_COOKIE}=${visitorId}; Max-Age=31536000; Path=/; SameSite=Lax`;
+}
+
+function shouldRecordVisit() {
+  try {
+    if (sessionStorage.getItem(SESSION_MARK_KEY)) {
+      return false;
+    }
+
+    sessionStorage.setItem(SESSION_MARK_KEY, "1");
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+export function getVisitorId() {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  const visitorId = getOrCreateVisitorId();
+  markCookie(visitorId);
+  return visitorId;
+}
+
+export function recordVisit() {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  if (!shouldRecordVisit()) {
+    return getVisitorId();
+  }
+
+  const visitorId = getVisitorId();
+
+  const entry = {
+    id: visitorId,
+    ts: new Date().toISOString(),
+    path: `${window.location.pathname}${window.location.search}${window.location.hash}`,
+  };
+
+  try {
+    const raw = localStorage.getItem(VISITOR_HISTORY_KEY);
+    const history = raw ? JSON.parse(raw) : [];
+    history.push(entry);
+
+    const trimmed = history.slice(-50);
+    localStorage.setItem(VISITOR_HISTORY_KEY, JSON.stringify(trimmed));
+  } catch {
+    // If storage is unavailable, we silently skip persistence.
+  }
+
+  return visitorId;
+}
+
+export async function sendVisitToServer({
+  visitorId,
+  model,
+  path,
+  location,
+} = {}) {
+  // Client-only tracking - visits are stored in localStorage only
+  // For GitHub Pages deployment, server endpoint is not available
+  // Implement alternative: send to a serverless service (Lambda, Firebase, etc.) if needed
+  
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  const resolvedVisitorId = visitorId || getVisitorId();
+  if (!resolvedVisitorId) {
+    return;
+  }
+
+  const payload = {
+    visitorId: resolvedVisitorId,
+    model,
+    location,
+    path:
+      path ||
+      `${window.location.pathname}${window.location.search}${window.location.hash}`,
+    ts: new Date().toISOString(),
+  };
+
+  // Store visit in localStorage for client-side analytics
+  try {
+    const raw = localStorage.getItem(VISITOR_HISTORY_KEY);
+    const history = raw ? JSON.parse(raw) : [];
+    history.push(payload);
+
+    // Keep last 100 visits
+    const trimmed = history.slice(-100);
+    localStorage.setItem(VISITOR_HISTORY_KEY, JSON.stringify(trimmed));
+  } catch {
+    // Ignore storage errors
+  }
+
+  // TODO: For production, consider sending to a serverless backend:
+  // - AWS Lambda + API Gateway
+  // - Firebase Cloud Functions
+  // - Vercel Edge Functions
+  // - Or use a third-party analytics service (Google Analytics, Plausible, etc.)
+  //
+  // Example with Firebase:
+  // const response = await fetch(
+  //   'https://your-firebase-project.cloudfunctions.net/recordVisit',
+  //   {
+  //     method: 'POST',
+  //     headers: { 'Content-Type': 'application/json' },
+  //     body: JSON.stringify(payload),
+  //   }
+  // ).catch(() => {}); // Ignore network errors
+}
+
+export function getCoarseLocation() {
+  if (typeof window === "undefined") {
+    return Promise.resolve(null);
+  }
+
+  try {
+    const cached = sessionStorage.getItem(LOCATION_CACHE_KEY);
+    if (cached) {
+      return Promise.resolve(JSON.parse(cached));
+    }
+  } catch {
+    // Ignore cache errors and fall back to live lookup.
+  }
+
+  if (!("geolocation" in navigator)) {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve) => {
+    navigator.geolocation.getCurrentPosition(
+      (position) => {
+        const location = {
+          lat: position.coords.latitude,
+          lon: position.coords.longitude,
+          accuracyMeters: position.coords.accuracy,
+        };
+        try {
+          sessionStorage.setItem(LOCATION_CACHE_KEY, JSON.stringify(location));
+        } catch {
+          // Ignore cache errors.
+        }
+        resolve(location);
+      },
+      () => resolve(null),
+      {
+        enableHighAccuracy: false,
+        maximumAge: 10 * 60 * 1000,
+        timeout: 8000,
+      }
+    );
+  });
+}

client/vite.config.js

@@ -0,0 +1,26 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import cesium from 'vite-plugin-cesium';
+
+// https://vite.dev/config/
+export default defineConfig(({ command }) => ({
+  // Use absolute base for dev server, relative base for GitHub Pages build
+  base: command === 'serve' ? '/' : './',
+  
+  plugins: [react(), cesium()],
+  
+  server: {
+    port: 5173,
+    // Development server config - no proxies needed
+    // All S3 requests handled client-side through AWS SDK
+  },
+  
+  publicDir: 'public',
+  
+  build: {
+    // Optimize for production
+    target: 'esnext',
+    minify: 'terser',
+    sourcemap: false,  // Set to true for debugging production builds
+  }
+}))

server/main.py

@@ -0,0 +1,100 @@
+import os
+import asyncio
+import uuid
+import aiofiles
+from pathlib import Path
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from fastapi.middleware.cors import CORSMiddleware
+
+app = FastAPI()
+
+# Enable CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Configuration
+DATA_DIR = Path("/app/data")
+UPLOAD_DIR = DATA_DIR / "uploads"
+CONVERTED_DIR = DATA_DIR / "converted"
+STATIC_DIR = Path("/app/static")
+BINARY_PATH = "/usr/local/bin/SplatTiler"
+
+# Ensure directories exist
+UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+CONVERTED_DIR.mkdir(parents=True, exist_ok=True)
+
+@app.post("/api/upload")
+async def upload_ply(
+    file: UploadFile = File(...),
+    lat: float = Form(0.0),
+    lon: float = Form(0.0)
+):
+    if not file.filename.lower().endswith(('.ply', '.splat')):
+        raise HTTPException(status_code=400, detail="Only .ply or .splat files are supported")
+
+    job_id = str(uuid.uuid4())
+    job_dir = CONVERTED_DIR / job_id
+    job_dir.mkdir(parents=True, exist_ok=True)
+    
+    input_path = UPLOAD_DIR / f"{job_id}_{file.filename}"
+    
+    try:
+        # Save uploaded file
+        async with aiofiles.open(input_path, "wb") as out_file:
+            while content := await file.read(1024 * 1024):  # Read in 1MB chunks
+                await out_file.write(content)
+            
+        # Run conversion
+        # Usage: SplatTiler -o <output_directory> -m 500000 [--lat <val> --lon <val>] <input_file>
+        print(f"Starting conversion for {job_id}...")
+        
+        cmd = [BINARY_PATH, "-o", str(job_dir), "-m", "500000"]
+        if lat != 0.0 or lon != 0.0:
+            cmd.extend(["--lat", str(lat), "--lon", str(lon)])
+        cmd.append(str(input_path))
+
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE
+        )
+        stdout, stderr = await process.communicate()
+        
+        if process.returncode != 0:
+            error_msg = stderr.decode() if stderr else "Unknown error"
+            print(f"Conversion failed: {error_msg}")
+            raise HTTPException(status_code=500, detail=f"Conversion failed: {error_msg}")
+
+        print(f"Conversion successful for {job_id}")
+        return {
+            "jobId": job_id,
+            "tilesetUrl": f"/data/converted/{job_id}/tileset.json"
+        }
+
+    except Exception as e:
+        print(f"Error processing file: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        # Cleanup input file to save space
+        if input_path.exists():
+            os.remove(input_path)
+
+# Mount converted data for access by Cesium
+app.mount("/data/converted", StaticFiles(directory=str(CONVERTED_DIR)), name="converted")
+
+# Serve React App
+app.mount("/assets", StaticFiles(directory=str(STATIC_DIR / "assets")), name="assets")
+
+@app.get("/{full_path:path}")
+async def serve_react_app(full_path: str):
+    file_path = STATIC_DIR / full_path
+    if file_path.exists() and file_path.is_file():
+        return FileResponse(file_path)
+    return FileResponse(STATIC_DIR / "index.html")

server/requirements.txt

@@ -0,0 +1,4 @@
+fastapi
+uvicorn
+python-multipart
+aiofiles