Scanner Scripts

Work in Progress...

Scanner Scripts

The scanner/ directory contains various python scripts for scanning and testing. Normally the webapp will call these scripts using node's child process module. However, to make development easy, each script has a simple demo or main method that is callable directly from python like so:

# from inside the scanner/ directory
python script_name.py

For the sake of simplicity, inter-process communication (between the node webapp, and the python scripts) is accomplished by piping the printed output from the python process into the input of the node process. To make parsing the messages simple, anything that is printed from a python script is printed in JSON format. This keeps everything human readable in the terminal, and also makes it incredibly easy to parse the messages in the webapp. Sometimes these JSON messages can even be passed along to the client (browser) side front-end javascript, without requiring any processing.

Currently there are a few bugs in libsweep and sweeppy. Therefore the scripts are rather verbose in attempting to catch errors and shutdown. As the underlying sdk becomes more robust, so too will the scanner code. There is a lot of room to clean things up.

See the scanner/ README for more details about the individual scripts.

The code from the scanner/ directory requires:

• python + numpy module
• physical hardware (sweep sensor + raspberry pi + motor HAT + motors + limitswitch)
• installation of libsweep or sweeppy

---

Dummy Version

The dummy_scanner/ directory contains dummy scripts that simulate the behavior of the normal scripts found in the scanner/ directory. These dummy scripts are used in place of the normal scanner code when the main node web application is run with the dummy flag.

node app.js -d

Just as with the normal scanner scripts, the dummy versions can also be tested directly:

# from inside the dummy_scanner/ directory
python script_name.py

Again, all scripts print in formatted JSON so the node webapp can easily parse the output.

The code from the dummy_scanner/ directory only requires:

• python + numpy module

The following are NOT required:

• any physical hardware (sweep sensor + raspberry pi + motor HAT + motors + limitswitch)
• installation of libsweep or sweeppy

---

Theory of Operation

The Sweep is a 2D scanning LiDAR device which uses a form of adaptive sampling. If you haven't read through the article on the Sweep's theory of operation, do so now: https://support.scanse.io/hc/en-us/articles/115006333327-Theory-of-Operation

The scanner scripts are designed around the Sweep's operation. Therefore it is crucial that you understand:

• the sweep gathers 2D scans. You can think of this as a 2 dimensional plane.
• the sweep delimits 360 degree scans by the reference 0 degree mark on the face of the device. The LED and thin groove line up with the 0 degree mark, and this never changes.
• the sweep operates at an assumed constant motor speed.

Using a 2D scanner to gather 3D scans is accomplished by:

• mounting the device 90 degree from the horizontal. You can think of this as shifting the 2D scan plane from the horizontal ground plane to a vertical plane. Picture a piece of paper flat on a table. Then imagine picking the paper up and pressing it against a wall like a poster.
• rotating the 2D vertical scan plane about its center vertical axis to cover all 3D dimensions. Because the 2D scanner captures an entire plane of information, the 2D scan plane need only rotate 180 degrees to capture a full 3D scan.

A 3D scan can be thought of as slices of a sphere, all passing through the sphere's center. The Sweep rotates continuously, but the base does not rotate continuously. In between each scan, the base rotates by a fixed interval such that the next 2D scan represents a different slice of the environment.

The Sweep uses a form of adaptive sampling, meaning there is no fixed interval between sensor readings in the 2D scan plane. Therefore it is impossible to guarantee a consistent angular resolution within a 2D scan plane (slice). However the scanner will try to match the angular spacing between slices with the expected or average angular resolution of a 2D scan. This produces a final scan that looks uniform, because the horizontal and vertical densities are relatively similar.

Recall that the Sweep rotates continuously. But there is an angular deadzone where the beam is passing over the base of the 3D scanner. The data from this angular deadzone is useless garbage. To be efficient, the scanner uses this angular deadzone as an opportunity to increment the base angle (ie: increment the slice of 3D space). Because the 0 degree mark does not fall within the deadzone, this requires a little bit of housekeeping to guarantee the proper base angle is used when converting each reading.