Structural State Vector Extraction from ecoSPLAT Gaussian Splat Reconstructions

Preliminary Methods, Results, and Instrument Design for the YEA Terrarium Analyst

Document ID: CNL-TN-2026-XXX Version: 0.1 Date: March 7, 2026 Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This technical note was developed with assistance from Claude (Anthropic, claude-sonnet-4-6). The AI contributed to methodology design, Python script development, data analysis pipeline construction, preliminary result interpretation, and manuscript drafting. The author takes full responsibility for the content, accuracy, and conclusions.

Abstract

This technical note describes the development and preliminary validation of a structural characterization method for 360° panoramic field station archives. Gaussian splat point clouds generated by the SHARP monocular reconstruction pipeline within the ecoSLAM/MacroscopeVR system are analyzed using a 10-parameter structural state vector capturing spatial geometry (linearity, planarity, sphericity, verticality, anisotropy) and radiometric character (green fraction, hue entropy, red-to-green ratio, brightness mean, saturation standard deviation). Parameters are extracted per terrarium cell and aggregated by spherical ring (zenith, upper, horizon, lower, nadir), yielding a 54-column structural matrix. Analysis of 454 terrarium reconstructions across 33 OBFS field stations demonstrates that the horizon ring linearity parameter is stable across seasons while green fraction tracks phenological state, that post-fire structural signatures are correctly identified as outliers, and that principal component analysis separates stations by biome and season along interpretable axes. These methods form the analytical foundation for the Terrarium Analyst instrument (LAB·03) in the YEA Laboratory suite.

1. Introduction

1.1 Background

The YEA (Your Ecological Address) platform maintains a network of 33 field stations affiliated with the Organization of Biological Field Stations (OBFS). Each station is documented with time-series 360° panoramic photography acquired across multiple seasons and years. The MacroscopeVR observatory system processes these panoramas through ecoSLAM, which decomposes each panorama into 25 perspective terrarium cells using a spherical grid and reconstructs each cell as a Gaussian splat using the SHARP monocular algorithm. The current ecoSPLAT archive holds 454 terrarium reconstructions representing 960 GB of point cloud and splat data.

A central research question emerges from this archive: can the structural information encoded in Gaussian splat point clouds serve as a quantitative proxy for ecological habitat state? If so, the archive becomes a multi-station, multi-season instrument for habitat monitoring — complementing species observation data and sensor streams already integrated into the YEA platform.

1.2 Research Objectives

This work pursues three objectives:

1. Design and implement a compact structural state vector extractable from ecoSPLAT point cloud files (_points.ply)
2. Validate that the vector captures ecologically meaningful variation across seasons and station types
3. Define the architecture of the Terrarium Analyst laboratory instrument that will expose this analysis interactively

1.3 Scope

This technical note covers Phase 1 of a two-phase development. Phase 1 uses the distilled point cloud (_points.ply) files only. Phase 2, described in Section 9, will extend the vector to 16 elements by incorporating opacity and Gaussian scale parameters from the full splat (.ply) files.

2. Background: The ecoSPLAT Pipeline

2.1 MacroscopeVR and ecoSLAM

MacroscopeVR is the observatory operating system hosting ecoSLAM, the ecological scene reconstruction pipeline. ecoSLAM accepts equirectangular 360° panorama images and decomposes them into perspective terrarium cells using a spherical grid defined in CNL-SP-2026-013. Each cell is processed through SHARP, a monocular Gaussian splatting algorithm, to produce a dense 3D reconstruction from the single perspective image.

2.2 The Spherical Grid

The 25 cells are distributed across five latitude rings:

Table 1. Spherical grid cell distribution by ring.

2.3 Point Cloud File Format

Each reconstructed terrarium cell produces two output files. The _points.ply distillation contains 1,179,648 vertices in binary little-endian format with per-vertex fields: xyz position (float32, three channels) and RGB color (uint8, three channels). The full g{NN}.ply file additionally encodes Gaussian opacity and covariance scale parameters used in Phase 2.

2.4 Archive Location

The canonical archive is located at:

/Library/WebServer/Documents/Archive/Media_Files/Images/360/Stations/stations/{slug}/
    terrariums/{slug}_{photopoint}_{season}_{year}/
        g{NN}.ply
        g{NN}_points.ply
        g{NN}.jpg
        grid.json

3. Methodology

3.1 Structural State Vector Design

The Phase 1 structural state vector contains 10 parameters per terrarium cell, organized into two groups: spatial geometry parameters derived from the xyz point distribution, and radiometric parameters derived from the RGB color distribution.

3.1.1 Spatial Parameters

The 1,179,648 xyz point positions form a 3×3 covariance matrix. Eigendecomposition via numpy.linalg.eigh yields eigenvalues λ₁ ≥ λ₂ ≥ λ₃ representing variance along the three principal spatial axes. Five shape indices are derived from these eigenvalues:

Table 2. Spatial parameters of the structural state vector.

These indices are not independent; they partition the variation in the covariance eigenvalues. L + P + S ≤ 1 by construction.

3.1.2 Radiometric Parameters

RGB vertex colors (uint8, range 0–255) are normalized to [0, 1] and converted to HSV using Python's colorsys module. Five radiometric features are computed:

Table 3. Radiometric parameters of the structural state vector.

3.2 Ring-Level Aggregation

Per-cell vectors are aggregated by spherical ring. For each of the five rings (zenith, upper, horizon, lower, nadir), the mean value of each parameter is computed across all cells in that ring. This yields five ring-level feature vectors of 10 parameters each, plus a panorama-level aggregate, producing 54 feature columns per terrarium row in the structural matrix.

3.3 Software Implementation

Analysis was performed in Python 3 using numpy (array operations and eigendecomposition), colorsys (RGB to HSV conversion), and struct (binary PLY header parsing). Statistical analysis used scikit-learn (StandardScaler, PCA, KMeans). Visualization used matplotlib. Scripts were developed on Data (MacBook Pro M4 Max) and migrated to Galatea (Mac Mini M4 Pro) at /Library/WebServer/Documents/Canemah/projects/yea3d/admin/lab/scripts/.

Four scripts implement the full pipeline (see Appendix A for usage details):

• describe_cell.py — single-cell 10-parameter extraction
• describe_panorama.py — full panorama ring portrait
• harvest_matrix.py — batch matrix construction
• analyse_matrix.py — PCA, clustering, and visualization

3.4 Dataset

The structural matrix was harvested from the full ecoSPLAT archive on Galatea. Archive traversal parses terrarium directory names in the pattern {slug}_{photopoint}_{season}_{year} to extract metadata. Rows with fewer than 20 successfully processed cells (of 25) were excluded. The resulting matrix contains 454 rows across 33 stations.

Table 4. Structural matrix season distribution.

PCA was performed on the 45 per-ring parameter columns (excluding panorama-level aggregates) after StandardScaler normalization. K-means clustering used k = 4, initialized from season-label centroids.

4. Results

4.1 Single-Station Seasonal Analysis

Clemson Baruch Institute (photopoint hobcaw001) provides a well-sampled four-season sequence in a temperate bottomland hardwood forest in South Carolina. Table 5 shows key structural parameters across seasons.

Table 5. Seasonal structural parameters, Baruch hobcaw001 (2021–2022).

The horizon L parameter varies by only 0.047 across the full annual cycle, confirming that linearity captures the permanent structural scaffold — the arrangement of stems, trunks, and branches — rather than seasonal foliage state. The Gf parameter tracks the expected deciduous phenological arc: near-zero in winter leaf-off, peak in summer, partial senescence in fall. Zenith Bmu inversely tracks canopy closure: sky fraction as seen through canopy gaps decreases as the canopy closes in summer.

The consistently elevated horizon L value (0.839 in summer) is partly attributable to a semi-permanent camera scaffold present in the field of view at this photopoint. This is a known condition at hobcaw001 and represents an instrumentation artifact discussed further in Section 7.

4.2 Dense Vegetation Anomaly: ELC Clackamas

The Environmental Learning Center (Clackamas County, Oregon) provides two contrasting photopoints:

clackamas001 is an open riparian corridor (horizon L = 0.44, summer Gf = 0.71). The low L value reflects the open canopy structure typical of a young alder-willow riparian corridor. Strong seasonal contrast is present.

clackamas002 records the highest Gf value in the dataset: 0.956 in summer. This extreme value results from the camera being situated inside dense herbaceous growth — the lens is substantially enclosed by vegetation, producing a scene that is dominated by green material in nearly all cells. The structural vector correctly flags this condition: high Gf is combined with low L and high S (spherical distribution), indicating a fully enclosed vegetated scene rather than a landscape perspective. This represents a case where the structural vector successfully detects a data collection anomaly without external annotation.

4.3 Network PCA

PCA on the 454-row, 45-column feature matrix (per-ring parameters, StandardScaler normalized) yielded the following variance explained:

Table 6. PCA variance explained, leading components.

PC1 is strongly loaded on horizon L, horizon Gf, and pano Gf. The dominant axis separates dense summer forested scenes (high PC1) from open winter scenes (low PC1). PC2 is loaded on zenith Bmu and nadir L, separating closed-canopy scenes from open-sky scenes.

Station PC1 ranking. Mean PC1 score across all panoramas separates stations into interpretable tiers. High-PC1 stations (mean > 2.0) include tropical and subtropical forested stations: La Selva Biological Station (Costa Rica), Luquillo (Puerto Rico), and temperate bottomland stations with strong summer development (Baruch, Sedgwick). Low-PC1 stations reflect open or structurally simple scenes.

4.4 Post-Fire Structural Signature: Gillicos Ranch

Gillicos Ranch returns a summer PC1 score of 10.2, a strong positive outlier. This station experienced a wildfire prior to the summer 2022 survey. The structural vector characterizes the post-fire scene accurately: very high L (standing dead snags and char-blackened stems produce strong linearity), near-zero Gf (no photosynthetically active vegetation), and elevated RG ratio (exposed char and soil are red-shifted relative to green vegetation). The outlier is not an analytical artifact but a structurally accurate characterization of a post-disturbance scene.

4.5 Closed-Canopy Conifer Signature: Tanglewood

Tanglewood returns a mean PC1 score of −3.8, a strong negative outlier in the opposite direction. This station is characterized by a dense mature conifer overstory with very low ground-level light. Near-zero zenith Bmu (completely closed canopy) combines with moderate Gf in upper rings but very low Gf in the horizon ring (shaded understory with sparse vegetation). This is a structurally distinctive closed-canopy conifer forest signature — ecologically coherent and distinct from the post-fire outlier despite both appearing at extremes of the PC1 distribution.

5. Discussion

5.1 Ecological Interpretability

The preliminary results support the central claim that Gaussian splat point cloud statistics carry ecologically interpretable structural information. The seasonal trajectory of Gf at Baruch follows the known deciduous phenological cycle. The stable inter-seasonal L value at the same station reflects the known permanence of woody structure. The post-fire detection at Gillicos and the dense-canopy signature at Tanglewood both correspond to documented site conditions rather than analytical noise.

The ability to distinguish these conditions from a single geometric and radiometric descriptor — without species-level identification, ground truth labels, or supervised training — suggests that structural state vectors may be a useful complement to biodiversity observation data for habitat characterization at the network scale.

5.2 Ring Differentiation

The five-ring aggregation scheme proves informative. The horizon ring carries the strongest structural signal for habitat discrimination, as expected: it captures the mid-field scene structure that most directly reflects vegetation architecture. The zenith ring effectively tracks canopy closure through Bmu. The nadir ring tracks ground cover composition. Upper and lower rings provide transitional information. This ring differentiation argues for retaining the per-ring structure in the feature matrix rather than collapsing to panorama-level aggregates alone.

5.3 Relationship to Established Structural Metrics

The spatial parameters L, P, S, and A are directly analogous to point cloud shape indices used in airborne LiDAR analysis [1, 2]. Their application to monocular Gaussian splat reconstructions represents an extension of these methods to ground-level, camera-derived data — a substantially different data type with different noise characteristics and spatial scale. The correspondence of results with expected ecological patterns suggests that the translation is productive, though formal validation against LiDAR-derived structural metrics at co-located stations remains future work.

6. Limitations

6.1 Monocular Reconstruction Fidelity

SHARP generates point clouds from single perspective images. Unlike multi-view or LiDAR-derived point clouds, monocular reconstructions may introduce systematic biases in depth estimation, particularly in scenes with limited texture, strong perspective foreshortening, or complex occlusion. The structural parameters derived from these point clouds therefore reflect the visual geometry of the reconstructed scene rather than the true 3D structure. Validation studies comparing SHARP-derived structural parameters against co-located LiDAR acquisitions are needed to characterize these biases.

6.2 Camera Artifacts

The hobcaw001 analysis (Section 4.1) identified a permanent camera scaffold as a contributor to elevated L values. Similar instrumentation artifacts — camera housings, mounting poles, solar panels — may be present at other photopoints and are not systematically flagged in the current pipeline. Manual inspection of outlier values is recommended until an automated artifact detection step is implemented.

6.3 Sample Size Imbalance

The dataset is unevenly distributed across seasons (92 fall to 125 spring, Table 4) and stations (from 1 to 7 panoramas per station). PCA and clustering results may be influenced by stations with larger archives. Analysis weighted by station rather than by panorama count would provide a more balanced network-level view.

6.4 Phase 1 Feature Completeness

The Phase 1 vector omits Gaussian opacity and scale parameters, which encode information about scene density and reconstruction confidence. Scenes with sparse point distributions (open sky, water surfaces) may be inadequately characterized by spatial geometry alone. Phase 2 extension to the full 16-element vector is expected to improve discrimination in these cases.

6.5 Geographic Bias

The 33-station network overrepresents the western United States and includes only two tropical stations (La Selva, Luquillo). PCA results and biome-level clustering should be interpreted with this geographic distribution in mind.

7. Conclusion

A 10-parameter structural state vector can be extracted from ecoSPLAT SHARP Gaussian splat point cloud files and used to characterize habitat structure at the network scale. The Phase 1 implementation demonstrates that spatial geometry parameters (particularly horizon ring linearity) capture permanent structural features independent of seasonal phenological state, while radiometric parameters (particularly green fraction) track vegetation phenology. Network PCA produces ecologically interpretable axes separating stations and seasons along greenness-structure and canopy closure dimensions. Anomalous scenes — post-fire disturbance, enclosed camera positions, closed-canopy conifers — are correctly identified without supervision.

These results support the development of the Terrarium Analyst (LAB·03) as an interactive instrument for habitat monitoring and multi-station ecological comparison within the YEA Laboratory. Phase 2 extension of the vector to 16 elements and formal validation against independent structural metrics will strengthen the ecological foundation of the instrument.

8. References

[1] Weinmann, M., Jutzi, B., Hinz, S., & Mallet, C. (2015). "Semantic point cloud interpretation based on optimal neighborhoods, relevant features and efficient classifiers." ISPRS Journal of Photogrammetry and Remote Sensing, 105, 286–304.

[2] Lague, D., Brodu, N., & Leroux, J. (2013). "Accurate 3D comparison of complex topography with terrestrial laser scanner: Application to the Rangitikei canyon (N-Z)." ISPRS Journal of Photogrammetry and Remote Sensing, 82, 10–26.

[3] Kerbl, B., Kopanas, G., Leimkühler, T., & Drettakis, G. (2023). "3D Gaussian Splatting for Real-Time Radiance Field Rendering." ACM Transactions on Graphics, 42(4). https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/

[4] Hamilton, M. P. (2026). "ecoSLAM Spherical Grid Specification." CNL-SP-2026-013. Canemah Nature Laboratory.

9. Appendices

Appendix A: Script Reference

A.1 describe_cell.py — Single-Cell Descriptor

Loads a _points.ply binary file and computes the 10-parameter Phase 1 structural state vector.

Usage:

python describe_cell.py <path_to_points.ply>

Dependencies: numpy, colorsys, struct

Key operations:

• Parses binary little-endian PLY header to extract vertex count and field offsets
• Loads xyz and rgb arrays
• Computes 3×3 covariance matrix; extracts eigenvalues via numpy.linalg.eigh
• Converts uint8 RGB to float [0,1], transforms to HSV via colorsys
• Applies green hue mask [90°, 150°] for Gf
• Computes Shannon entropy on 36-bin hue histogram for Hc

A.2 describe_panorama.py — Panorama Ring Portrait

Processes all 25 cells of a terrarium directory, produces per-ring aggregate output.

Usage:

python describe_panorama.py <terrarium_directory> [--csv]

Output: Per-ring means of all 10 structural parameters (Table 5 in this document was generated by this script).

A.3 harvest_matrix.py — Batch Matrix Construction

Traverses the full station archive, processes every terrarium, and writes structural_matrix.csv.

Usage:

python harvest_matrix.py [--stations-root PATH] [--output structural_matrix.csv]

Archive traversal pattern: {STATIONS_ROOT}/{slug}/terrariums/{slug}_{photopoint}_{season}_{year}/

Output columns (59 total): station, photopoint, season, year, terrarium, n_cells, then per-ring columns {ring}_{param} (45 columns), then panorama-level aggregates pano_{param} (9 columns).

A.4 analyse_matrix.py — Statistical Analysis

Reads structural_matrix.csv, runs PCA and k-means clustering, produces four diagnostic plots.

Usage:

python analyse_matrix.py structural_matrix.csv [--output-dir plots/]

Plot outputs: PCA biplot, seasonal clusters in PC1-PC2 space, station PC1 ranking, per-ring Gf seasonal boxplots.

Appendix B: Pending Work

The following items are identified for completion prior to v1.0 release:

1. Migrate structural_matrix.csv to Galatea lab/scripts/ and verify STATIONS_ROOT resolves correctly against the canonical Stations/ archive
2. Re-run harvest_matrix.py on Galatea to confirm all 454 terrariums are accessible post-archive consolidation
3. Assign RESOLVE biome labels to all 33 stations from lookup_cache for labeled PCA clustering
4. Phase 2: extend describe_cell.py to read opacity and Gaussian scale from full .ply files (6 additional parameters)
5. Phase 2: re-harvest matrix with 16-element vectors and rerun PCA
6. Formal validation of SHARP-derived structural parameters against co-located LiDAR acquisitions

Document History