Optical

Introduction

The Optical Sensor is a light-based sensor that uses reflected light to detect objects, identify colors, and measure brightness and hue. When set to gesture mode, it can also recognize hand movements in front of the sensor.

Below is a list of all available methods:

Methods – Detect objects, colors, and gestures.

• object_detected – Calls a function when an object is detected.

• object_lost – Calls a function when an object is lost.

• gesture_up – Calls a function when an up gesture is detected.

• gesture_down – Calls a function when a down gesture is detected.

• gesture_left – Calls a function when a left gesture is detected.

• gesture_right – Calls a function when a right gesture is detected.

• gesture_enable – Set the Optical Sensor to gesture mode.

• gesture_disable – Set the Optical Sensor to color mode.

• set_light – Set the on or off state of the LED.

• set_light_power – Set the brightness of the LED.

• is_near_object – Returns whether or not a detected object is near the Optical Sensor.

• color – Returns the closest detected color match.

• brightness – Returns the brightness of a detected object.

• hue – Returns the hue of a detected object.

• get_gesture – Return the detected gesture.

• rgb – Returns the RGB values detected by the Optical Sensor.

• object_detect_threshold – Sets the threshold for detecting objects.

• installed – Returns whether or not an Optical Sensor is connected to the Brain.

Constructors – Manually initialize and configure an Optical Sensor.

• Optical – Creates an Optical Sensor.

Methods

object_detected

object_detected registers a callback function for when an object is detected.

Usage:
object_detected(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def detected():
    drivetrain.stop()
    brain.screen.set_cursor(1, 1)
    brain.screen.print("object detected")
    wait(0.5,SECONDS)
    brain.screen.clear_screen()

# Display a message when the Optical Sensor
# detects an object
drivetrain.drive(FORWARD)
optical_1.object_detected(detected)

object_lost

object_lost registers a callback function for when an object is lost.

Usage:
object_lost(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def lost():
    drivetrain.stop()
    brain.screen.set_cursor(1, 1)
    brain.screen.print("object lost")
    wait(0.5,SECONDS)
    brain.screen.clear_screen()

# Display a message when the Optical Sensor
# loses sight of on object
drivetrain.drive(REVERSE)
optical_1.object_lost(lost)

gesture_up

gesture_up registers a callback function for when an upward gesture is detected.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
gesture_up(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def detect_gesture_up():
    drivetrain.drive_for(FORWARD, 100, MM)

# Run detect_gesture_up when the Optical Sensor detects 
# an upward gesture
optical_1.gesture_enable()
optical.gesture_up(detect_gesture_up)

gesture_down

gesture_down registers a callback function for when an downward gesture is detected.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
gesture_down(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def detect_gesture_down():
    drivetrain.drive_for(REVERSE, 100, MM)

# Run detect_gesture_down when the Optical Sensor detects 
# a downward gesture
optical_1.gesture_enable()
optical.gesture_down(detect_gesture_down)

gesture_left

gesture_left registers a callback function for when an leftward gesture is detected.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
gesture_left(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def detect_gesture_left():
    drivetrain.turn_for(LEFT, 360, DEGREES)

# Run detect_gesture_left when the Optical Sensor detects 
# a leftward gesture
optical_1.gesture_enable()
optical.gesture_left(detect_gesture_left)

gesture_right

gesture_right registers a callback function for when an rightward gesture is detected.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
gesture_right(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
arg	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def detect_gesture_right():
    drivetrain.turn_for(RIGHT, 360, DEGREES)

# Run detect_gesture_right when the Optical Sensor detects 
# a rightward gesture
optical_1.gesture_enable()
optical.gesture_right(detect_gesture_right)

gesture_enable

gesture_enable enables gesture mode.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
gesture_enable()

Parameters	Description
	This method has no parameters.

def detect_gesture_right():
    drivetrain.turn_for(RIGHT, 360, DEGREES)

# Run detect_gesture_right when the Optical Sensor detects 
# a rightward gesture
optical_1.gesture_enable()
optical.gesture_right(detect_gesture_right)
wait(15, MSEC)

gesture_disable

gesture_disable disables gesture mode.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
gesture_disable()

Parameters	Description
	This method has no parameters.

# Display detected colors after the Optical Sensor
# detects a right gesture.
optical_1.gesture_enable()
while not optical_1.get_gesture().type == GestureType.RIGHT:
    wait(20, MSEC)
# Disable gestures and return to colors.
optical_1.gesture_disable()
while True:
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    brain.screen.print(optical_1.color())
    wait(0.1, SECONDS)

set_light

set_light sets Optical Sensor’s LED to on or off.

Usage:
set_light(state)

Parameters	Description
state	The state to set the light or the percentage of power in the range 0 to 100. The state can be either of the following: LedStateType.OFF (0 percent) LedStateType.ON (100 percent) integer – A brightness value given as a percent from 0 to 100.

# Turn the LED on and off forever
while True:
    optical_1.set_light(LedStateType.ON)
    wait(0.5, SECONDS)
    optical_1.set_light(LedStateType.OFF)
    wait(0.5, SECONDS)

set_light_power

set_light_power sets the light power of the Optical Sensor’s LED.

Usage:
set_light_power(value)

Parameters	Description
value	The power level to set the light from 0 to 100 as a percent.

# Turn the LED light on at different
# intensities
optical_1.set_light(LedStateType.ON)
wait(2, SECONDS)
optical_1.set_light_power(10)
wait(2, SECONDS)
optical_1.set_light_power(100)

is_near_object

is_near_object returns whether or not the Optical Sensor is nearby an object.

• True – The sensor is near an object.

• False – The sensor is not near an object.

Usage:
is_near_object()

Parameters	Description
	This method has no parameters.

# Stop driving when Optical Sensor is near an object
while True:
    if optical_1.is_near_object():
        drivetrain.stop()
    else:
        drivetrain.drive(FORWARD)

color

color returns the color detected by the Optical Sensor.

Usage:
color()

Parameters	Description
	This method has no parameters.

# Stop the robot if the Optical Sensor detects red
while True:
    if optical_1.color() == Color.RED:
        drivetrain.stop()
    else:
        drivetrain.turn(RIGHT)

brightness

brightness returns the brightness detected by the Optical Sensor.

Usage:
brightness(readraw)

Parameters	Description
readraw	Optional. A boolean value to read raw brightness data instead of percentage: True – Return the raw data. False – Return brightness as a percentage.

# Display the brightness of a red object detected
# by the Optical Sensor
drivetrain.turn(RIGHT)
while not optical_1.color() == Color.RED:
    wait(50, MSEC)
drivetrain.stop()
brain.screen.print(optical_1.brightness())

hue

hue returns the value of the hue detected by the Optical Sensor.

Usage:
hue()

Parameters	Description
	This method has no parameters.

# Set a variable hue, to the value of the hue detected by
# the Optical Sensor
while True:
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    if 290 < optical_1.hue() < 350:
        brain.screen.print("Pink!")
        wait(0.1,SECONDS)
    else:
        brain.screen.print("Not pink.")
        wait(0.1,SECONDS)

get_gesture

get_gesture returns the gesture detected by the Optical Sensor.

A gesture is the motion of a detected object by the Optical Sensor. So if an object moves upward in the view of the Optical Sensor, that is a gestureUp. On the other hand if an object moves downward, that is a gestureDown. The same goes for gestureLeft and gestureRight.

Usage:
get_gesture(newobject).type

Parameters	Description
newobject	Optional. A boolean value which determines whether or not to create a new Gesture object: True – Create a new Gesture object. False – Do not create a new Gesture object.

optical_1.gesture_enable()
while True:
    # Spin if a gesture is detected
    if optical_1.get_gesture().type == GestureType.NONE:
        brain.screen.clear_screen()
        brain.screen.set_cursor(1, 1)
        brain.screen.print("No gesture")
        wait(0.5, SECONDS)
    else:
        drivetrain.turn_for(RIGHT, 360, DEGREES)

rgb

rgb returns the Optical Sensor’s RGB value.

Usage:
rgb(raw)

Parameters	Description
raw	Optional. A boolean value to determine if you return raw or processed values: True – Return the raw value. False – Do not return the raw value.

# Display the rgb values and brightness detected
# by the Optical Sensor.
brain.screen.set_font(FontType.MONO12)
while True:
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    brain.screen.print(optical_1.rgb())
    wait(0.1, SECONDS)

object_detect_threshold

object_detect_threshold sets the object detection threshold. This method also returns the newly set threshold.

Usage:
object_detect_threshold(value)

Parameters	Description
value	A number in the range 0 - 255. A value of 0 will just return the current value.

def detected():
    # The Brain will print that an object was detected on
    # the Brain's screen.
    brain.screen.print("object detected")
    brain.screen.next_row()
    optical_1.object_detect_threshold(254)
    optical_1.object_detected(detected_closer)

def detected_closer():
    # Detect an object closer to the sensor.
    brain.screen.print("Detected closer")
    
# Run detected when the Optical Sensor detects an object.
optical_1.object_detect_threshold(100)
optical_1.object_detected(detected)

# Alternate example
stage = 0

def detected():
    global stage
    if stage == 0:
        brain.screen.print("Get closer...")
        brain.screen.next_row()
        stage = 1
        optical_1.object_detect_threshold(254)
        optical_1.object_detected(detected_closer)

def detected_closer():
    global stage
    if stage == 1:
        brain.screen.print("Too close!")
        brain.screen.next_row()
        stage = 2

# Detect an object first with the detect threshold at 100,
# then again at 254
optical_1.object_detect_threshold(100)
optical_1.object_detected(detected)
wait(15, MSEC)

installed

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

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

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

Usage:
installed()

Parameters	Description
	This method has no parameters.

# Display a message if the Optical Sensor
# is installed.
if optical_1.installed():
    brain.screen.print("Installed!")

Constructors

Constructors are used to manually create Optical objects, which are necessary for configuring an Optical Sensor outside of VEXcode.

For the examples below, the configured Optical Sensor will be named optical_1 and will be used in all subsequent examples throughout this API documentation when referring to Optical class methods.

Optical

Optical creates an Optical Sensor.

Usage:
Optical(port)

Parameter	Description
port	Which Smart Port that the Optical Sensor is connected to as PORT followed by the port number, ranging from 1 to 12.

# Construct an Optical Sensor "optical_1" with the
# Optical class
optical_1 = Optical(Ports.PORT1)

# Display the brightness of a red object detected
# by the Optical Sensor
drivetrain.turn(RIGHT)
while not optical_1.color() == Color.RED:
    wait(50, MSEC)
drivetrain.stop()
brain.screen.print(optical_1.brightness())