Skip to main content

A Fun Example: Dog-on-Couch Detector

Here is a whimsical example of how you could use Groundlight in your home to keep your dog off the couch. This document will guide you through creating a complete application. If the dog is detected on the couch, the application will play a pre-recorded sound over the computer's speakers, instructing the dog to get off the couch. Be sure to record your own voice so that your dog pays attention to you.


  • Groundlight SDK with Python 3.7 or higher
  • A supported USB or network-connected camera
  • A pre-recorded sound file (e.g., get_off_couch.mp3)
  • A couch and a dog are recommended for proper end-to-end testing.


Ensure you have Python 3.7 or higher installed, and then install the Groundlight SDK and OpenCV library:

pip install groundlight opencv-python pillow pyaudio

Creating the Application

  1. First, log in to the Groundlight application and get an API Token.

  2. Next, we'll write the Python script for the application. Import the required libraries:

import time
import cv2
from groundlight import Groundlight
from PIL import Image
import pyaudio
import wave
  1. Define a function to capture an image from the camera using OpenCV:
def capture_image():
cap = cv2.VideoCapture(0)

ret, frame =

if ret:
# Convert to PIL image
return Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
return None
  1. Define a function to play the pre-recorded sound:
def play_sound(file_path):
CHUNK = 1024
wf =, 'rb')

p = pyaudio.PyAudio()

stream =,

data = wf.readframes(CHUNK)

while data:
data = wf.readframes(CHUNK)


  1. Write the main application loop:
gl = Groundlight()

detector = gl.get_detector("Dog on Couch Detector")

while True:
image = capture_image()
if image:
iq = gl.submit_image_query(image=image, detector=detector, wait=60)
answer = iq.result.label
if answer == "YES":
print("Dog detected on the couch!")
except Exception as e:
print(f"Error submitting image query: {e}")
print("Failed to capture image")

# Sleep for a minute before checking again

This application captures an image using the capture_image function, then submits it to the Groundlight API for analysis. If the dog is detected on the couch, it plays the pre-recorded sound using the play_sound function.

Save the script as and run it: