README.md
1# SweepPy
2
3Python Scanse Sweep LiDAR library. Work with Python2 and Python3.
4
5Requires `libsweep.so` to be installed.
6
7### Installation
8
9Install `sweeppy` module for Python3 locally:
10
11```bash
12python3 setup.py install --user
13```
14
15### Example for testing
16
17In the following, replace `/dev/ttyUSB0` with your device's port name. This executes [`__main__.py`](sweeppy/__main__.py) (also works without the installation step).
18
19```bash
20python -m sweeppy /dev/ttyUSB0
21```
22
23### Windows:
24
25The installed sweep library architecture must match the python version. Ie: if you are using a x86 (32bit) version of python, you must install the x86 (32bit) verison of libsweep.
26
27```bash
28python.exe setup.py install --user
29```
30
31In the following: replace `COM5` with your device's port name (check "Device Manager -> COM Ports").
32
33```bash
34python.exe -m sweeppy COM5
35```
36
37### Quick Start
38
39```python
40from sweeppy import Sweep
41
42with Sweep('/dev/ttyUSB0') as sweep:
43 sweep.start_scanning()
44
45 for scan in sweep.get_scans():
46 print('{}\n'.format(scan))
47```
48
49Note: `Sweep` objects need to be scoped using the `with` statement for resource management.
50
51See [sweeppy.py](sweeppy/__init__.py) for interface and [example](sweeppy/__main__.py) for example usage.
52
53
54
55
56### Interface
57
58```
59class Sweep:
60 def __init__(self, port, bitrate = None) -> Sweep
61
62 def start_scanning(self) -> None
63 def stop_scanning(self) -> None
64
65 def get_motor_ready(self) -> bool
66 def get_motor_speed(self) -> int (Hz)
67 def set_motor_speed(self, speed) -> None
68
69 def get_sample_rate(self) -> int (Hz)
70 def set_sample_rate(self, speed) -> None
71
72 def get_scans(self) -> Iterable[Scan]
73
74 def reset(self) -> None
75
76class Scan:
77 self.samples -> Sample
78
79class Sample:
80 self.angle -> int (milli-degree)
81 self.distance -> int (cm)
82 self.signal_strength -> int ([0:255])
83```
84
85See the [libsweep README](https://github.com/scanse/sweep-sdk/tree/master/libsweep#device-interaction) for a description of how to use a related interface.
86
87Additionally, it is recommended that you read through the sweep [Theory of Operation](https://support.scanse.io/hc/en-us/articles/115006333327-Theory-of-Operation) and [Best Practices](https://support.scanse.io/hc/en-us/articles/115006055388-Best-Practices).
88
89### Interpret Sample
90```python
91sample.angle
92```
93The sample's angle (azimuth) represents the rotation of the sensor when the range measurment was taken. The value is reported in milli-degrees, or 1/1000 of a degree. For example, a `sample.angle` value of `180000 milli-degrees` equates to `180 degrees` (half of a complete rotation). Successive samples of the same scan will have increasing angles in the range 0-360000.
94
95```python
96sample.distance
97```
98The sample's distance is the range measurement (in cm).
99
100```python
101sample.distance
102```
103The sample's signal strength is the strength or confidence of the range measurement. The value is reported in the range 0-255, where larger values are better.
104
105
106### License
107
108Copyright © 2016 Daniel J. Hofmann
109
110Distributed under the MIT License (MIT).
111