Distance

Introduction

The Distance Sensor can detect objects directly in front of it and measure their distance. The 1st gen sensor uses sonar for detection, while the 2nd gen sensor uses a classroom-safe laser and can also estimate an object’s size and velocity.

For the examples below, the configured Distance Sensors will be named distance_1 and will be used in all subsequent examples throughout this API documentation when referring to Distance and Sonar class methods.

Below is a list of all available methods:

Getters – Return data from the Distance Sensor.

• is_object_detected – (1st and 2nd gen) Returns whether an object is within range.

• distance – (1st gen) Returns the distance to the nearest object.

• object_distance – (2nd gen) Returns the distance to the nearest object in inches, millimeters, or centimeters.

• object_velocity – (2nd gen) Returns the speed of a detected object in meters per second.

• object_size – (2nd gen) Returns the estimated size of the detected object (small, medium, large).

• installed – (1st and 2nd gen) Returns whether the Distance Sensor is connected to the Brain.

Constructors – Manually initialize and configure a Distance Sensor.

• Sonar – Create a (1st gen) Distance Sensor.

• Distance – Create a (2nd gen) Distance Sensor.

Getters

is_object_detected

is_object_detected returns a Boolean indicating whether the Distance Sensor detects an object within range.

• True - The Distance Sensor detects an object.

• False - The Distance Sensor does not detect an object.

Usage:
distance_1.is_object_detected()

Parameters	Description
	This method has no parameters.

# Turn until an object is detected
drivetrain.turn(RIGHT)
while not distance_1.is_object_detected():
    wait(15, MSEC)
drivetrain.stop()
brain.screen.print("Object detected!")

distance

distance returns the current distance from the Distance Sensor and a detected object as a float.

Note: This is a (1st gen) Distance Sensor method.

Usage:
distance_1.distance(units)

Parameters	Description
units	Optional. The unit that represents the distance: INCHES MM (default) – Millimeters

# Display the distance to an object
if distance_1.is_object_detected():
    print("Distance: ")
    print(distance_1.distance(MM))
else:
    print("No object detected")

object_distance

object_distance returns the distance between the Distance Sensor and the nearest object as a float.

Note: This is a (2nd gen) Distance Sensor method.

Usage:
distance_1.object_distance(units)

Parameters	Description
units	Optional. The unit that represents the distance: INCHES MM (default) – Millimeters DistanceUnits.CM – Centimeters

# Drive forward until an object is 200 mm away
while distance_1.object_distance(MM) > 200:
    drivetrain.drive(FORWARD)
drivetrain.stop()

object_velocity

object_velocity returns the velocity of a detected object as a float, measured in meters per second. A positive value indicates the object is moving toward the Distance Sensor (2nd gen), while a negative value indicates it is moving away.

Note: This is a (2nd gen) Distance Sensor method.

Usage:
distance_1.object_velocity()

Parameters	Description
	This method has no parameters.

# Display the velocity of a moving object
while True:
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    brain.screen.print("Velocity: ")
    brain.screen.print(distance_1.object_velocity())
    wait(100, MSEC)

object_size

object_size returns an ObjectSizeType, which represents the estimated size of the detected object based on how much of the Distance Sensor (2nd gen)’s field of view it occupies:

• ObjectSizeType.NONE – No object is detected, or the object is so close that it fills the entire field of view.

• ObjectSizeType.SMALL – The object occupies a small portion of the field of view.

• ObjectSizeType.MEDIUM – The object occupies roughly half of the field of view.

• ObjectSizeType.LARGE – The object occupies most of the field of view.

Note: This is a (2nd gen) Distance Sensor method.

Usage:
distance_1.object_size()

Parameters	Description
	This method has no parameters.

installed

installed returns a Boolean indicating whether the Distance Sensor is connected to the Brain.

• True - The Distance Sensor is connected to the Brain.

• False - The Distance Sensor is not connected to the Brain.

Usage:
distance_1.installed()

Parameters	Description
	This method has no parameters.

Constructors

Constructors are used to manually create Distance and Sonar objects, which are necessary for configuring a Distance Sensor (2nd gen) or (1st gen) outside of VEXcode.

Sonar

Sonar creates a Distance Sensor (1st gen).

Usage:
distance_1 = Sonar(port)

Parameter	Description
port	Which Smart Port that the Distance Sensor (1st gen) is connected to as Ports.PORT followed by the port number, ranging from 1 to 12.

# Create a Sonar object in Port 1
distance_1 = Sonar(Ports.PORT1)

Distance

Distance creates a Distance Sensor (2nd gen).

Usage:
distance_1 = Distance(port)

Parameter	Description
port	Which Smart Port that the Distance Sensor (2nd gen) is connected to as Ports.PORT followed by the port number, ranging from 1 to 12.

# Create a Distance object in Port 1
distance_1 = Distance(Ports.PORT1)