Distance#

Initializing the Distance Class #

The Distance constructor creates a Distance object in the specified Smart Port:

Parameter	Description
`port`	A valid Smart Port that the Distance Sensor is connected to.

# Construct a Distance Sensor "distance" with the
# Distance class.
distance = Distance(Ports.PORT1)

This distance object will be used in all subsequent examples throughout this API documentation when referring to Distance class methods.

Class Methods #

object_distance()#

The object_distance(units) method returns the distance the Distance Sensor is currently reading. The Distance Sensor will return a large positive number if no object is detected.

Parameters	Description
units	Optional. A valid DistanceUnits type. The default unit is `MM`.

Returns: The distance to the detected object in the specified units.

# Get the distance detected by the Distance Sensor in mm.
value = distance.object_distance()

# Get the distance detected by the Distance Sensor in inches.
value = distance.object_distance(INCHES)

object_size()#

The object_size() method returns an estimate of the size of the detected object.

Returns: The estimated size of the detected object.

# Get the object size detected by the Distance Sensor.
size = distance.object_size()

object_velocity()#

The object_velocity() method returns the velocity of the detected object. The velocity is calculated by the change in distance over the change in time.

Returns: The velocity of the detected object in meters per second.

is_object_detected()#

The is_object_detected() method checks if an object is detected.

Returns: True if an object is detected. False if an object is not detected.

changed()#

The changed(callback, arg) method registers a callback function for when the detected object changes.

Parameters	Description
callback	A function that will be called when the detected object changes.
arg	Optional. A tuple that is used to pass arguments to the callback function.

Returns: An instance of the Event class.

# Define function distance_changed().
def distance_changed():
    # The Brain will print that the distance changed on
    # the Brain's screen.
    brain.screen.print("distance changed ")
# Run distance_changed() when the value detected by the 
# Distance Sensor changes.
distance.changed(distance_changed)

object_rawsize()#

The object_rawsize() method returns the raw value of object size the sensor is detecting.

Returns: The raw size of the detected object.

# Get the raw size of the object detected by the
# Distance Sensor.
size = distance.object_rawsize()

installed()#

The installed() method checks if the Distance Sensor is connected.

Returns: True if the Distance Sensor is connected. False if it is not.