Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Radar Application ======

===== Overview =====

This app will log vehicular traffic on a road or thoroughfare.  It will also measure the speed of each vehicle and determine if the speed limit that you set is being exceeded, and it can be configured to text you when someone exceeds the speed limit.  The pictures are chosen to achieve the best possible view of a vehicle's license plate.  Additionally, the pictures of each vehicle are uploaded to Google Photos if you wish.  

===== Getting started =====

Set up Vizy in the location that you think works best.  Here are the general guidelines for setting up Vizy.

  - It's likely that you will need a [[wiki:zoom_getting_started|zoom lens]] if you want to be able to read the characters on the license plate of a vehicle, but a zoom lens isn't necessary.  Without a zoom lens will more likely get a picture of the entire vehicle without a zoom lens.  
  - Vizy should be pointed at about 45 degrees with respect to the roadway, so that you can get a good estimate of the velocity, while also being able to see the license plate.  
  - You have a choice of pointing Vizy 45 degrees to the left or to the right when facing the roadway.  Bear in mind that if you point Vizy to the left (for example), you will get pictures of the rear license plate for cars traveling to the left, and you will get pictures of the front license plate for cars traveling to the right.  Not all vehicles have front license plates, so pointing Vizy in the direction that is more important to you is a good rule of thumb.  If it makes no difference, pick either direction. 
  - An outdoor enclosure will be necessary if you want Vizy to stay outside, but it's probably a good idea to get the Radar application working without an outdoor enclosure first. 

Begin by turning on your Vizy and pointing your browser to it.  (Please refer to the [[wiki:vizy_getting_started|getting started guide]] if you need help with connecting to your Vizy, etc.)  Run the Radar application by clicking on the ☰ icon in the upper right corner and selecting **Apps/examples**. Then scroll over to Radar in **Apps**, then click on **Run**.

{{wiki:image_1597.jpg?450}}

You'll be presented with a screen similar to below. The image at the top of the screen is the live video feed of what Vizy sees (for example, the road). Various controls (buttons, sliders) are shown below the video feed, which we'll describe in more detail.   

{{wiki:image_1601.jpg?600}}

One thing you'll probably notice is that the video window is dark.  This is to prevent motion blur in the images.  That is, normally the Radar application is taking footage from daytime/outside lighting conditions and the vehicles are typically moving quickly across the image.  To fix the dark image, bring up the settings dialog by clicking on the **Settings** button, and enable **Low light**, which will allow you to better test indoors. 

{{wiki:image_1600.jpg?450}}

To test, take your hand and swipe it across the image such that your hand appears on one side of the image and exits the opposite side of the image.  It should detect your hand and estimate its speed as shown below.

{{wiki:image_1599.jpg?600}}

==== Media Queue ====

You'll notice that when detecting vehicles (or your hand), the recent detections are displayed below the live feed with the measured speed.  

{{wiki:image_1603.jpg?700}}
 
==== Calibration ====

The Radar application measures the distance a vehicle travels between each frame and then fits a straight line across all measurements.  This method is quite accurate, but it needs to be calibrated to accurately associate the pixels in the image with actual distances so it can estimate the speed of the vehicle in either kph or mph.  This can be done by either driving your vehicle in front of Vizy at a known speed, or by estimating the speed of a given vehicle.   Because of camera geometry, lanes closer to Vizy's lens will have faster apparent motion than lanes further away.  For this reason, it's best to calibrate the speed of vehicles moving in both directions to achieve the most accurate speed measurements.  (Currently, the Radar application assumes there are only two lanes, one for each direction of travel.)
  
To calibrate, just click on the image that contains the vehicle that you know the speed of.  Then click anywhere within the image to bring up the calibration dialog.

{{wiki:image_1604.jpg?450}}

Type in the speed and click on **Calibrate**.  This will set the calibration for this image.  Note, it won't change the speeds of other detection images, however, but new vehicle detections will be affected.  

For the most accurate results, be sure to calibrate in both directions.  That is, calibrate using an image of a vehicle going in one direction.  And calibrate using an image of a vehicle going in the opposite direction.  You only need to do this once for each direction.  This can be done by driving in front of Vizy at a known speed in both directions.  Or it can be done by simply estimating the velocity of a given vehicle (the lazy method), but this usually results in less accurate speed estimates. 

Once it's calibrated, Vizy will provide accurate speed measurements from then on.  If you accidentally knock Vizy such that its angle or position is significantly changed, just use an older image to realign Vizy such that it's looking at the same section of the roadway as before.  In general, small changes in angle and position don't affect the speed estimates significantly. 
   

===== Controls and settings =====

The **Brightness** slider gives you control over the brightness of the pictures and live video feed.

==== Settings dialog ====

Clicking on **Settings** will bring up the Settings dialog. 

{{wiki:image_1606.jpg?450}}

  * **Speed limit**: This adjusts the speed limit.  Vehicles that exceed this speed are "speeders". 
  * **Sensitivity**: Lowering the sensitivity will reduce any false positive vehicle detections and increasing the sensitivity will reduce the false negative vehicle detections (not detecting vehicles that are present). 
  * **Kilometers per hour**: Check this if you prefer kilometers per hour to miles per hour.
  * **Camera pointing left**: Check this if Vizy is pointing to the left.  Leave it unchecked if Vizy is pointing to the right.  This helps Vizy determine when to take a picture such that it will get the best possible view of the license plate.  
  * **Upload to Google Photos**:  Check this if you want the media items in the media queue to be uploaded to Google Photos.  Google services need to be configured, however.  See the section on [[wiki:radar_app#Configuring Google services|Configuring Google services]].
  * **Text speeders**: Vizy will text you a picture when it detects a vehicle that is exceeding the speed limit.  See [[wiki:texting|texting]].
  * **Low light**: When using under low light conditions (e.g. indoors), check this.  
  * **Debug**: Check this to display various debugging information including a sampling graph. 

==== Configuring Google services ====

Your Vizy can upload pictures to Google Photos. In order for Vizy to upload photos to the cloud, you'll want to [[wiki:google_cloud_setup3|set up Google services]]. 

Once you've set this up, other Vizy applications will have access to Google cloud services such as Photos, Gmail, Sheets, and Google Drive.

==== Texting ====

Vizy's texting service allows Vizy to send you updates (typically to your phone).  For example, Vizy can text you a picture when it detects a vehicle that is exceeding the speed limit if you configure it to do so in the [[wiki:radar_app#Settings dialog|settings]].  See [[wiki:texting|texting]] to learn how to configure the texting service. 

==== Text commands ====

Currently, the only text command that the Radar application supports is **mrv** (most recent vehicle). For example, to get information (description and picture) of the most recent vehicle that was detected:

{{wiki:IMG_4768.jpg?300}}

Or you can get the N most recent vehicles by adding a number:

{{wiki:IMG_4769.jpg?300}}

===== Customizations, tweaks, etc. =====

==== Deploying Vizy ====

You can either have Vizy sitting outside, pointing at a roadway, all comfy and cozy in an [[wiki:outdoor_enclosure_getting_started|outdoor enclosure]], or you can point Vizy at a roadway through a window from indoors.  You will likely want Vizy to be able to see a good amount of detail of the vehicle's license plate, which typically requires use of a 
[[wiki:zoom_getting_started|zoom lens]].  This [[wiki:simple_outdoor_enclosure_mounting|guide ]] describes how to mount your Vizy outdoor enclosure.  


==== Customized handlers ====

For more advanced users who want to add their own custom features, the Radar application has handler code for various events and for text messages.  The handler code is in ''/home/pi/vizy/apps/radar/handlers.py''.  Note, you can bring up the handler code easily from [[wiki:vizy_editor#Text editor|Vizy's built-in text editor]] by clicking on the ☰ button in the text editor and selecting ''handlers.py''.  Note also, once you change ''handlers.py'' you can simply click reload/refresh on your browser and Vizy will automatically restart the application and your code changes will take effect.

{{wiki:image_1605.jpg}}

=== Event handler ===

The event handler function is **handle_event**, which is called when an event occurs:

<sxh python>
def handle_event(self, event):
    print(f"handle_event: {event}")
</sxh>

Here, the argument **self** is the Radar class object and **event** is a dictionary with various values depending on the event. 
 In particular, the **event_type** value specifies the type of the event.  The different types are listed below:

  * **vehicle**: This event indicates that a vehicle has been detected.  The **image**, **speed**, **timestamp**, and various other fields are included. 
  * **daytime**: This event indicates when it has entered the "daytime" state and has enough light to reliably identify species.
  * **nighttime**:  This event indicates when it has entered the "nighttime" state and is inactive.


=== Text handler ===

The text handler function is **handle_text**, which is called when Vizy receives a [[wiki:texting|text message via Telegram]].  **handle_text** is called when none of Vizy's text handlers know how to handle the text message.  

<sxh python>
def handle_text(self, words, sender, context):
    print(f"handle_text from {sender}: {words}, context: {context}")
</sxh>

Here, the argument **self** is the Radar class object, and **words** is the list of words in the text message.  **sender** is the person that sent the text and **context** is a list of contextual strings.
Documentation

User Tools

Site Tools

Page Tools
