4. Object Methods - ryan-brazeal-ufl/OpenPyLivox GitHub Wiki

There are many methods associated with an OpenPyLivox object. These methods are where the magic happens, and provide an easy way to programmatically operate a Livox lidar sensor. Using the OpenPyLivox library, an out-of-the-box Livox Mid-40 sensor, and a DHCP network router, a Python program that collects point cloud data from the sensor can be created using the following 9 lines of code. The point cloud data will be saved to a file named, points.csv, and this file can be directly opened in CloudCompare.

import openpylivox as opl
sensor = opl.openpylivox(True)
sensor.auto_connect()
sensor.dataStart_RT()
sensor.saveDataToFile("points.csv",0,10.0)   #collect exactly 10.0 seconds of data
while True:
   if sensor.doneCapturing():
      break
sensor.disconnect()

The OpenPyLivox object connection methods are so important, they were given their own section in this Wiki. Please view section 2: Sensor Connection Options for the full details.

The .disconnect() method is used to:

• end data capturing and close the exported .csv file (if not already done)
• inform the Livox lidar sensor that the user is disconnected from it
• properly close the user computer's data and command ports

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      Disconnected from Mid-40 sensor at IP: 192.168.1.42
      *** Error trying to disconnect from Mid-40 sensor at IP: 192.168.1.42
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.disconnect()

The .lidarSpinUp() method is used to:

• send the switch to normal power state command to the sensor
• if the sensor is in standby or power-saving mode, this command will pause the runtime execution until the sensor has reached normal mode
• if the sensor is already in normal mode, this method has no affect

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent lidar spin up request
      192.168.1.42 --> FAILED to spin up the lidar
      192.168.1.42 --> lidar is spinning up, please wait...
      192.168.1.42 --> lidar is ready
      192.168.1.42 --> incorrect lidar spin up response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.lidarSpinUp()

The .lidarSpinDown() method is used to:

• send the switch to power-saving state command to the sensor
• if the sensor is already in power-saving mode, this method has no affect
• power-saving mode causes the rotating prisms (Risley mechanism) inside the lidar sensor to stop spinning, but the sensor is still powered on and able to reconnect

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent lidar spin down request
      192.168.1.42 --> FAILED to spin down the lidar
      192.168.1.42 --> incorrect lidar spin down response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.lidarSpinDown()

The .lidarStandBy() method is used to:

• send the switch to stand-by state command to the sensor
• if the sensor is already in stand-by mode, this method has no affect
• not exactly sure what stand-by mode actually does, as the rotating prisms inside the lidar sensor are still spinning (maybe only the laser is shut off?)

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent lidar stand-by request
      192.168.1.42 --> FAILED to set lidar to stand-by
      192.168.1.42 --> incorrect lidar stand-by response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.lidarStandBy()

The .readExtrinsic() method is used to:

• query the lidar sensor and request it to send the current values for the extrinsic parameters
• upon successfully receiving the current values, the OpenPyLivox sensor object's extrinsic parameters are updated

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent read extrinsic parameters request
      192.168.1.42 --> FAILED to read extrinsic parameters
      192.168.1.42 --> incorrect read extrinsic response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.readExtrinsic()

The .setExtrinsicToZero() method is used to:

• send the command to the lidar sensor to reset the extrinsic parameters all to zero
• the OpenPyLivox sensor object's extrinsic parameters are also reset to zero
• the .readExtrinsic() method is automatically called as part of this method in order to check that the command was successfully received and applied by the lidar sensor

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent set extrinsic parameters to zero request
      192.168.1.42 --> FAILED to set extrinsic parameters to zero
      192.168.1.42 --> incorrect set extrinsics to zero response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setExtrinsicToZero()

The .setExtrinsicTo(x, y, z, roll, pitch, yaw) method is used to:

• send the command to the lidar sensor to set the extrinsic parameters to specific values
• the OpenPyLivox sensor object's extrinsic parameters are also set to the same specific values
• the .readExtrinsic() method is automatically called as part of this method in order to check that the command was successfully received and applied by the lidar sensor

The required arguments for this method are:

1. x a float value that represents the x cartesian coordinate of the sensor, in meters
2. y a float value that represents the y cartesian coordinate of the sensor, in meters
3. z a float value that represents the z cartesian coordinate of the sensor, in meters
4. roll a float value that represents the roll orientation angle of the sensor, in degrees
5. pitch a float value that represents the pitch orientation angle of the sensor, in degrees
6. yaw a float value that represents the yaw orientation angle of the sensor, in degrees

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      *** Error - one or more of the extrinsic values specified are not of the correct type ***
      192.168.1.42 <-- sent sent extrinsic parameters request
      192.168.1.42 --> FAILED to set extrinsic parameters
      192.168.1.42 --> incorrect set extrinsic parameters response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setExtrinsicTo(12.345, -23.456, 34.567, -0.05, 8.77, -174.14)

The .setCartesianCS() method is used to:

• send the command to the lidar sensor instructing it to transmit the point cloud data stream using Cartesian coordinates (x, y, z) for the points

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent change to Cartesian coordinates request
      192.168.1.42 --> FAILED to set Cartesian coordinate output
      192.168.1.42 --> incorrect change coordinate system response (Cartesian)
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setCartesianCS()

The .setSphericalCS() method is used to:

• send the command to the lidar sensor instructing it to transmit the point cloud data stream using raw Spherical coordinates (distance, zenith angle, azimuth angle) for the points

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent change to Spherical coordinates request
      192.168.1.42 --> FAILED to set Spherical coordinate output
      192.168.1.42 --> incorrect change coordinate system response (Spherical)
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setSphericalCS()

The .setRainFogSuppression(OnOff) method is used to:

• send the command to the lidar sensor instructing it to turn on or off the rain/fog suppression functionality built into the sensor's firmware

The required argument for this method is:

1. OnOff a boolean value that states if rain/fog suppression should be used (True) or not (False)

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent turn on/off rain/fog suppression request
      192.168.1.42 --> FAILED to set rain/fog suppression value
      192.168.1.42 --> incorrect set rain/fog suppression response
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setRainFogSuppression(True)

The .setDynamicIP() method is used to:

• send the command to the lidar sensor instructing it to now use a dynamic IP address
• dynamic IP address assignment is performed by a DHCP server (e.g., a home network router usually performs this task) so the sensor will require to be connected to a DHCP server in order to operate
• the runtime execution will be force killed (exited) when this command is executed because the lidar sensor needs to be rebooted (powered off then back on) in order for the new network setting to be applied
• if you are using a Mac computer, view these instructions to have your computer act as a DHCP server (very convenient if you don't have access to a home network router)

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      Changed IP from 192.168.1.42 to dynamic IP (DHCP assigned)
      ************ PROGRAM ENDED - MUST REBOOT SENSOR ************
      192.168.1.42 --> FAILED to change to dynamic IP (DHCP assigned)
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setDynamicIP()

The .setStaticIP(ipAddress) method is used to:

• send the command to the lidar sensor instructing it to now use the specified static IP address
• static IP addresses do not require the use of a DHCP router
• the runtime execution will be force killed (exited) when this command is executed because the lidar sensor needs to be rebooted (powered off then back on) in order for the new network setting to be applied

The required argument for this method is:

1. ipAddress a string value that states the new IP address to be assigned to the sensor

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      Changed IP from 192.168.1.42 to a static IP of 192.168.1.43
      ************ PROGRAM ENDED - MUST REBOOT SENSOR ************
      192.168.1.42 --> FAILED to change static IP (must be 192.168.1.11 to .80)
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.setStaticIP("192.168.1.42")

The .dataStart() method is used to:

• ** DEPRECATED AS OF VERSION 1.0.1, USE .dataStart_RT() or .dataStart_RT_B() INSTEAD**
• send the command to the lidar sensor instructing it to begin transmitting the point cloud data stream to the computer's IP address using the data port number
• start a a new synchronous (simultaneous) thread in the user's computer that handles receiving the point cloud data stream, this allows the main program it continue it's runtime execution
• just because you can hear the lidar sensor spinning and it appears to be 'on', does not mean that data is being exported out of it
• it was quickly determined by users that the approach taken to capture the point cloud data within an ASCII CSV file was producing very POOR PERFORMANCE, as a result the .dataStart() method is being deprecated.

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent start data stream request
      192.168.1.42 --> FAILED to start data stream
      192.168.1.42 --> incorrect start data stream response
      192.168.1.42 --> data stream already started
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.dataStart()

The .dataStart_RT() method is used to:

• send the command to the lidar sensor instructing it to begin transmitting the point cloud data stream to the computer's IP address using the data port number
• start a a new synchronous (simultaneous) thread in the user's computer that handles receiving the point cloud data stream, this allows the main program it continue it's runtime execution
• just because you can hear the lidar sensor spinning and it appears to be 'on', does not mean that data is being exported out of it
• this method was introduced in v1.0.1 in order to IMPROVE PERFORMANCE for capturing the point cloud data in a CSV file

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent start data stream request
      192.168.1.42 --> FAILED to start data stream
      192.168.1.42 --> incorrect start data stream response
      192.168.1.42 --> data stream already started
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.dataStart_RT()

The .dataStart_RT_B() method is used to:

• send the command to the lidar sensor instructing it to begin transmitting the point cloud data stream to the computer's IP address using the data port number
• start a a new synchronous (simultaneous) thread in the user's computer that handles receiving the point cloud data stream, this allows the main program it continue it's runtime execution
• just because you can hear the lidar sensor spinning and it appears to be 'on', does not mean that data is being exported out of it
• this method was introduced in v1.0.2 in order to IMPROVE PERFORMANCE for capturing the point cloud data in a simple binary data file
• the Library Function .convertBin2CSV(filePathAndName,deleteBin=True/False) can then be called to convert the OpenPyLivox binary point cloud data file into a comma delimited ASCII file (.CSV) at any time after the binary data file has been closed

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent start data stream request
      192.168.1.42 --> FAILED to start data stream
      192.168.1.42 --> incorrect start data stream response
      192.168.1.42 --> data stream already started
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.dataStart_RT_B()

The .dataStop() method is used to:

• send the command to the lidar sensor instructing it to stop transmitting the point cloud data stream
• end the synchronous data handling thread
• no noticeable difference in the sound or other operation of the lidar sensor is heard or seen when this happens

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 <-- sent stop data stream request
      192.168.1.42 --> FAILED to stop data stream
      192.168.1.42 --> incorrect stop data stream response
      192.168.1.42 --> data stream already stopped
      Not connected to Mid-40 sensor at IP: 192.168.1.42

Usage Example,

sensor.dataStop()

The .saveDataToCSV(filePathAndName, secsToWait, duration) method is used to:

• ** DEPRECATED AS OF VERSION 1.0.2, USE .saveDataToFile(filePathAndName, secsToWait, duration) INSTEAD**
• inform the data handling thread that the point cloud data being received, starting in the value of the secsToWait argument, number of seconds from now, should be stored in memory for a total number of seconds equal to the duration argument value
• after the duration number of seconds of data has been stored, the data handling thread stops storing any additional data and the currently stored data is written to the filePathAndName CSV file. IMPORTANT NOTE: the extrinsic parameter values are currently NOT being utilized when the point cloud data is being written to the CSV file, in the future the user will have the option to have these parameters be applied or not when creating a CSV file.

The required arguments for this method are:

1. filePathAndName a string value that states the absolute or relative path and filename for the CSV file, the file extension '.csv' is not required and will automatically be included if not part of the filename
2. secsToWait a float value that states the number of seconds to delay the start of data capturing after the command has been sent
3. duration a float value that states the total number of seconds of data capturing, a value of 0 states that data capturing is to continue for an indefinite amount of time and therefore manually stopped by the user

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 --> unknown firmware version
      192.168.1.42 --> * ISSUE: saving data, negative duration
      192.168.1.42 --> * ISSUE: saving data, duration too big
      192.168.1.42 --> * ISSUE: saving data, negative time to wait
      192.168.1.42 --> * ISSUE: saving data, time to wait too big
      192.168.1.42 --> * ISSUE: saving data, file path and name missing
      192.168.1.42 --> WARNING: data stream not started, no CSV file created
      192.168.1.42 --> CAPTURING DATA...
      192.168.1.42 --> writing data to file: *points.csv* (DEPRECATED in v1.0.1)
      192.168.1.42 --> writing real-time data to file: *points.csv*
      192.168.1.42 --> WARNING: no point cloud data was captured
      192.168.1.42 --> Incorrect lidar packet version

Usage Example,

sensor.saveDataToCSV("points", 1.5, 12.34)

The .closeCSV() method is used to:

• ** DEPRECATED AS OF VERSION 1.0.2, USE .closeFile() INSTEAD**
• inform the data handling thread that the currently stored point cloud data is all that is required and that the data should now be written to the CSV file and then closed
• this method is primarily used when the .saveDataToCSV(...) method is called and the duration argument is set equal to 0, read above for further information

If .showMessage is True, then the messages printed to the screen include the following.

      192.168.1.42 --> closed CSV file: *points.csv*
                       (points: 123456 good, 9876 null, 133332 total)

Usage Example,

sensor.closeCSV()

The .saveDataToFile(filePathAndName, secsToWait, duration) method is used to:

• inform the data handling thread that the point cloud data being received, starting in the value of the secsToWait argument, number of seconds from now, should be written to the filePathAndName file for a total number of seconds equal to the duration argument value
• after the duration number of seconds of data has been stored, the data handling thread stops capturing any additional data.
• the type of data collected (i.e., ASCII or BINARY) depends on which .dataStart_... method was called.
• IMPORTANT NOTE: the extrinsic parameter values are currently NOT being utilized when the point cloud data is being written to the data file, in the future the user will have the option to have these parameters be applied or not when creating a data file.

The required arguments for this method are:

1. filePathAndName a string value that states the absolute or relative path and filename for the data file.
2. secsToWait a float value that states the number of seconds to delay the start of data capturing after the command has been sent
3. duration a float value that states the total number of seconds of data capturing, a value of 0 states that data capturing is to continue for an indefinite amount of time and therefore manually stopped by the user

If .showMessage is True, then the possible messages printed to the screen include any of the following.

      192.168.1.42 --> unknown firmware version
      192.168.1.42 --> * ISSUE: saving data, negative duration
      192.168.1.42 --> * ISSUE: saving data, duration too big
      192.168.1.42 --> * ISSUE: saving data, negative time to wait
      192.168.1.42 --> * ISSUE: saving data, time to wait too big
      192.168.1.42 --> * ISSUE: saving data, file path and name missing
      192.168.1.42 --> WARNING: data stream not started, no CSV file created (DEPRECATED in v1.0.2)
      192.168.1.42 --> WARNING: data stream not started, no data file created
      192.168.1.42 --> CAPTURING DATA...
      192.168.1.42 --> writing data to file: *points.csv* (DEPRECATED in v1.0.1)
      192.168.1.42 --> writing real-time data to ASCII file: *points.csv*
      192.168.1.42 --> writing real-time data to BINARY file: *points.bin*
      192.168.1.42 --> WARNING: no point cloud data was captured
      192.168.1.42 --> Incorrect lidar packet version

Usage Example,

sensor.saveDataToFile("points.csv", 1.5, 12.34)

The .closeFile() method is used to:

• inform the data handling thread that the currently captured point cloud data is all that is required and that the data file is to be closed
• this method is primarily used when the .saveDataToFile(...) method is called and the duration argument is set equal to 0, read above for further information

If .showMessage is True, then the messages printed to the screen include the following.

      192.168.1.42 --> closed ASCII file: *points.csv*
                       (points: 123456 good, 9876 null, 133332 total)
      192.168.1.42 --> closed BINARY file: *points.bin*
                       (points: 123456 good, 9876 null, 133332 total)

Usage Example,

sensor.closeFile()

The .resetShowMessages() method is used to:

• reset the .showMessages property of the OpenPyLivox sensor object back to the initial value specified when the object was instantiated
• this method works well when a user wants to specifically turn on or off information message(s) being displayed by another method or property, at a specific point within the program's execution

This method itself, never prints an information message to the screen.

Usage Example,

sensor.showMessage = True
sensor.setExtrinsicTo(12.345, -23.456, 34.567, -0.05, 8.77, -174.14)
sensor.resetShowMessages()

Previous Page  |  Next Page