Quick Start

The quickest way to get up and running is with nodar-quickstart.sh.

Download nodar-quickstart.sh

Note: After downloading, you should make nodar-quickstart.sh executable: chmod +x nodar-quickstart.sh

./nodar-quickstart.sh <uuid or download link> --run

This will

  • Install the .deb packages
  • Install a very minimal dataset to ${HOME}/.config/nodar/downloads/datasets
  • Launch nodar_viewer
  • Launch hammerhead to run on the dataset

If you want to manually get the dataset, you can download it here: nodar_data_day_highway_01_minimal.zip

After that, all you need to do is to click Connect in nodar_viewer :

On your first run, you will be asked to enter your activation key that you received by email (something like ABCDE-ABCDE-ABCDE-ABCDE).

  • -c: sets the path for the configuration files
  • -s: sets the path for the images used for playback
  • -l: tells Hammerhead to loop over the playback data

You can visualize the output by opening nodar_viewer in another terminal and clicking Connect:


Playback from Other Sources

nodar-quickstart.sh plays back data from file. Specifically, it invokes hammerhead with a command like:

hammerhead -c "config/" -s "topbot/"

which sets the path to the configuration files and to a folder containing topbot images.

To playback directly from cameras, you will omit the -s option and instead modify the master_config.ini file. At the moment we support 2 options:

  1. Direct readout of Lucid cameras
  2. Reading through a network interface

Lucid Cameras

If you have Lucid cameras that you want to use, then you should modify the master_config.ini with your camera IDs:

camera_source = lucid

# [string] Camera serial numbers specifying left and right camera
# Camera serial numbers can be found on the label attached to camera body
camera_left_id = 231001324
camera_right_id = 231001327

and call hammerhead without the -s option:

hammerhead -c "config/"

Topbot Publisher

If you want to use other types of cameras, then you will be in charge of synchronizing them. You should then modify the master_config.ini with the IP address and port of your topbot publisher, and specify the dimensions of the images you will be providing:

# [string] Specify camera source
# This can be one of:
#   'lucid'                  - Lucid cameras (default if empty)
#   'zmq://<ipv4>:<port>'    - ZMQ topbot publisher (e.g., 'zmq://127.0.0.1:5000')
#   'ros2://<topic>'         - ROS2 topbot subscriber (e.g., 'ros2:///nodar/topbots')
camera_source = zmq://127.0.0.1:5000

# [int] Specify width and height for the camera source
# This is used when camera_source is set to zmq:// or ros2://
# This is not used if camera_source is set to lucid
camera_source_width = 2880
camera_source_height = 1860

As with the Lucid cameras, you would then call hammerhead without the -s option:

hammerhead -c "config/"

These examples describe how to use the Topbot Publisher in much more detail:

C++ ZMQ Topbot Publisher

Python ZMQ Topbot Publisher

C++ ROS2 Topbot Publisher

Python ROS2 Topbot Publisher

Configuration Files

Both hammerhead and nodar_viewer can be used on the command line. Almost everything you need to run those programs is packaged in the .deb files, with 3 notable exceptions:

  • extrinsics.ini
  • intrinsics.ini
  • master_config.ini

These files will be unique to your camera system, so you must create them yourself. As the names imply, they need to contain the extrinsics, intrinsics, and high-level configuration settings for how you want to run Hammerhead. You can find documentation for these files here:

There are 2 primary ways to pass these files to Hammerhead:

  1. Pass the directory with these configuration files as a command-line option:
hammerhead -c config/

where the config/ looks like:

config/
├── extrinsics.ini
├── intrinsics.ini
└── master_config.ini
  1. Save the config files in your home directory, specifically, ${HOME}/.config/nodar/config/:
${HOME}/.config/nodar/config/
├── extrinsics.ini
├── intrinsics.ini
└── master_config.ini

and run hammerhead without the -c option.

Typically, you will use Option 1. if you are experimenting with different configurations, and Option 2. once you have finalized your configuration.

nodar_viewer doesn't use these config files. You can (and should) run it with no options.

Images

There are 3 primary ways to pass images to Hammerhead:

  1. Use the -s option to point to a directory containing sequentially-numbered topbot images.

topbot == image where a synchronized left and right image are stacked vertically (left on top, right on bottom)

  1. Use Lucid cameras and provide their IDs in the master_config.ini (camera_left_id and camera_right_id).
  2. Publish topbot images using one of our communication interfaces (we recommend ZMQ). See our C++ and Python examples for more details.