Skip to content

getting-started.md

Latest commit

 

History

History
130 lines (87 loc) · 4.46 KB

getting-started.md

File metadata and controls

130 lines (87 loc) · 4.46 KB
Raw

Getting Started

cev-sim is a browser-based autonomous vehicle and cev-sim workbench. It uses Next.js and React for the UI, Three.js for the 3D simulator, a visual scripting canvas for node programs, and an external Python orchestrator process for ROS-style topic integration.

Requirements

  • Node.js >=22.22.2 <23 and npm.
  • Python 3.10–3.13 only for the Gymnasium client in python/. See Python headless.
  • The ROS orchestrator is a separate optional repository. See ROS Integration.

Install

Fastest path — fetch and run the installer (requires git). When nvm already has Node.js 22.22.2, the installer switches to it. When that version is missing, it asks whether to install it with nvm and make it the default.

curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/main/install.sh | bash

Options:

# custom directory
curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/main/install.sh | bash -s -- --dir ~/ev-sim

# reproducible Alpha release tag (once published)
curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/v0.2.0/install.sh \
  | bash -s -- --ref v0.2.0

# clone + install + production build
curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/main/install.sh | bash -s -- --build

# clone + install + start the dev server
curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/main/install.sh | bash -s -- --start

--ref accepts a tag, branch, or commit. --branch remains a compatibility alias for --ref.

The installer creates .env.local and asks whether to enable the marketplace. Enter, y, or yes writes CEV_SIM_MARKETPLACE_ENABLED=1. n or no writes 0. An existing assignment is kept unless --marketplace or --no-marketplace is passed. A run with no terminal creates the file and leaves that setting unchanged, which leaves the marketplace enabled.

When visual-source-registry.json is absent, the installer creates it with a local owned-lab grant so editor Import can upload models. The default path is server/data/visual-source-registry.json. CEV_SIM_VISUAL_SOURCE_REGISTRY, or CEV_SIM_DATA_DIR when that registry variable is unset, selects another path from the environment or .env.local. An existing registry is kept.

If you already cloned the repo:

npm ci

A manual clone does not create server/data/visual-source-registry.json. Copy the owned-lab grant in Development, or re-run the installer, before using editor Import.

Run The App

npm run dev

Open the local URL printed by Next. Press Escape to open the app menu. From there you can switch between:

  • Scripting — visual node editor.
  • Simulation — vehicles, sensors, and scenario playback.
  • Environment Editor — author roads, buildings, props, and import real-world geography.

For a production-style local run:

npm run build
npm run start

npm run start launches server/App.js, which serves Next through Express on PORT or 3000.

Useful Commands

npm run dev
npm run build
npm run start
npm run lint
npm test

npm test runs the Node built-in test runner against tests/*.test.js.

Optional Orchestrator

Live ROS-style topics are served by a separate repository:

git clone https://github.com/cornellev/orchestrator.git
cd orchestrator
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

By default cev-sim expects:

  • WebSocket topics at ws://localhost:8080.
  • Message type sync at http://localhost:8090.

To enable the orchestrator's ROS 2 bridge, run it from a ROS 2 environment:

ROS_ENABLED=true python main.py

See ROS Integration for the integration boundary and current topic usage.

Optional Scenario Assets

CommonRoad scenarios are not committed to this repo. Download them from https://gitlab.lrz.de/tum-cps/commonroad-scenarios and place the scenarios folder under public/, creating paths like:

public/scenarios/recorded/NGSIM/Peachtree/USA_Peach-1_1_T-1.xml

See Assets before adding large or generated files.

Optional: Earth Import

To preview Google Photorealistic 3D Tiles in the environment editor, add a Google Maps API key to .env.local:

NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_key_here

Restart the dev server after adding the key. See Earth Import for the full workflow.