REALM (Robotic Environment for Autonomous Learning and Mapping) extended with the Visual Place Cell Encoding (VPCE) model — a biologically inspired framework for generating spatially structured, place-cell-like activation patterns from robot-acquired visual input using unsupervised feature clustering and radial basis function encoding.
This repository is a fork of REALM developed at the USF BioRobotics Lab. It extends the base simulation infrastructure with the VPCE model and serves as the active codebase for ongoing revisions targeting publication in a peer-reviewed journal.
VPCE models hippocampal place-cell-like representations without relying on odometry, path integration, ground-truth coordinates, or task feedback. The model processes point-of-view images collected during robot exploration, extracts high-dimensional visual features, and clusters them in feature space to define a population of visual place cells. Each place cell is characterized by the center and spread of a cluster; activation is computed via a radial basis function over the distance between a new observation and the stored cluster centroids.
- Feature Extraction — Each image is passed through a pretrained ResNet50 combined with handcrafted descriptors (HOG, color histograms, spatial histograms) to produce a multimodal feature vector.
- Ensemble Formation — Feature vectors are clustered using k-means or GMM. Each cluster centroid defines a visual place cell and its receptive field in feature space.
- Activation Encoding — New observations are encoded as a graded activation pattern across the ensemble using RBF scoring against stored centroids.
- Spatial proximity encoding
- Boundary and wall separation (statistically validated)
- Local remapping under structural change
- Population sparseness and spatial information content
- Multi-field place cell emergence under GMM clustering (preliminary)
This repository tracks active revisions to the VPCE model following peer review. Current development priorities include:
- Reframing the biological motivation around primate spatial view cells
- Explicit repositioning of the RBF assumption as a modeling design choice
- Addition of statistical significance tests across all evaluation metrics
- Conversion of tabular results to distributional figures
- Investigation of sparsity mechanisms (thresholding, k-winners-take-all)
- Integration of VPCE as a state representation module for RL agents
macOS:
brew install python@3.11Linux:
sudo apt-get install python3.11Windows: Install Python 3.11 from the Microsoft Store to avoid PATH issues.
Download and install from the Cyberbotics website.
Linux users: Do not install Webots via Snap. Use the
.debpackage or tarball instead.
Windows: git-scm.com
Linux: sudo apt-get install git
macOS: brew install git
git clone <your-repo-url>
cd REALM-VPCEpython setup/realm_install.pyThis will:
- Find Python 3.11 on your system
- Create
realm_venvwith all dependencies - Add the project root to the venv's Python path
- Generate
runtime.inifiles in all Webots controller directories
To remove the environment:
python setup/realm_install.py --uninstallmacOS/Linux:
source realm_venv/bin/activateWindows:
realm_venv\Scripts\activateIf you add a new controller under
simulation/controllers/, re-runpython setup/add_runtime_ini.pyto generate itsruntime.ini.
REALM-VPCE/
├── setup/
│ ├── realm_install.py # Install / uninstall script
│ ├── add_runtime_ini.py # Generates Webots runtime.ini files
│ └── requirements.txt # Venv dependencies
│
├── realm_tools/
│ ├── robot_lib/
│ │ ├── hambot.py # Base robot class (sensors, motors, supervisor)
│ │ ├── my_robot.py # User extension template (inherits HamBot)
│ │ └── robot_tools.py # Shared robot utility functions
│ ├── simulation_lib/
│ │ ├── environment.py # Environment class and environment objects
│ │ ├── maze_parser.py # XML maze file parser
│ │ └── webots_torch_environment.py # Gymnasium environment skeleton
│ └── image_lib/
│ ├── feature_extractor.py # CNN feature extraction (ResNet50 + HOG)
│ └── image_feature_lib.py # Image processing utilities
│
├── simulation/
│ ├── controllers/
│ │ ├── example/ # Example Webots controller
│ │ └── calibration/ # Keyboard-driven calibration controller
│ ├── protos/ # HamBot and world object Webots protos
│ └── worlds/ # Webots world files and maze XMLs
│
├── data/
│ └── DataCache/ # Temp files used by the display system
│
└── docs/ # Figures and documentation assets
The intended workflow when forking this repo for a new experiment:
- Robot logic — subclass
HamBotinmy_robot.pyand add experiment-specific methods (action sets, observation processing, etc.) - Environment — fill in the
WebotsEnvskeleton inwebots_torch_environment.pywith your observation space, reward function, and episode logic - Controllers — add new Webots controllers under
simulation/controllers/then re-runadd_runtime_ini.py - Personal files — your personal robot subclass (e.g.
yourname_robot.py) can be gitignored so the template stays clean for others
A keyboard-driven controller is provided for manually testing robot behaviour in Webots:
| Key | Action |
|---|---|
| Arrow Up | Forward |
| Arrow Down | Backward |
| Arrow Left | Turn left |
| Arrow Right | Turn right |
| Any other key | Stop |
Open simulation/worlds/calibration.wbt in Webots to use it.
- HamBot Reference
- Simulation & Webots Guide
- Controller Setup Guide
- Webots Controller Guide
- Gymnasium API Reference
- Stable-Baselines3 Docs
This work was supported in part by NSF IIS Robust Intelligence grant #1703225 — Experimental and Robotics Investigations of Multiscale Spatial Memory Consolidation in Complex Environments, University of South Florida.