Vicinal

Vicinal traces your lot on a Ring camera frame, scores how much of the picture looks past your own ground, proposes a privacy mask in Ring's vertex format, and drafts the neighbor notice.

Comment

Vicinal

Privacy-aware camera framing, built around the property line.

Inspiration

A Ring camera does not know where the lot ends. Its frame often includes the sidewalk, the street, or a neighbor's door, and the person who installed it rarely has a way to quantify how much of that picture extends beyond their property.

Ring already stores privacy zones as polygons and provides coarse location information. These capabilities are easy to overlook in favor of yet another motion alert.

Vicinal starts with a line a person can actually draw. A model does not know the property boundary. The owner does.

What It Does

Vicinal connects to a Ring camera, lets the owner trace their property boundary on a still image, and estimates how much of the camera's frame extends beyond that boundary and remains outside the privacy zones already configured.

Measuring Visual Overreach

Vicinal divides the image into a 160 × 90 grid and calculates the proportion of cells that fall outside the traced property boundary and are not already masked by existing privacy zones.

$$ \text{overreach} = \frac{\text{unmasked cells outside the lot}} {160 \times 90} $$

The resulting score provides a coarse, measurable indication of potential visual overreach. It is a grid-based estimate, not a legal determination or a precise measurement of real-world area.

Privacy-Zone Recommendations

From the traced boundary, Vicinal proposes privacy-zone rectangles using Ring's {x, y} coordinate format, with normalized coordinates ranging from 0 to 1.

It also generates four documents based on the camera's available country and state information:

  • Neighbor Notice — A draft notice explaining the camera's privacy boundaries.
  • Door Sign — A proposed sign describing the camera's use.
  • Privacy Record — A one-page record documenting the privacy assessment.
  • Audio Decision — A draft assessment based on the applicable jurisdiction rules.

The jurisdiction table and generated documents are intended for human review. They are not legal advice.

Important: Ring's configurations API is read-only for this workflow. Vicinal proposes privacy zones but cannot apply them automatically. The recommended coordinates must be copied into the Ring app manually.

How We Built It

Vicinal is a local Python application built with FastAPI and HTTPX. FastAPI serves a single-page interface, while a lightweight HTTPX client communicates with the Ring Partner API.

API base URL: https://api.amazonvision.com

Ring API Integration

Vicinal uses the following endpoints:

Method Endpoint Purpose
GET /v1/devices Retrieves device status, capabilities, location, and configurations.
GET /v1/devices/{id}/location Retrieves the device's available location information.
GET /v1/devices/{id}/configurations Reads existing configuration, including privacy-zone data.
POST /v1/devices/{id}/media/image/download Requests the latest available still image.

When the API returns a pre-signed image URL, Vicinal follows the redirect without forwarding the bearer token to the image host.

Interface and Geometry

The application uses a dark, survey-inspired layout. The camera still serves as the canvas for three layers:

  • Property boundary: Traced manually by the owner.
  • Existing privacy zones: Displayed from the camera's available configuration.
  • Proposed privacy mask: Generated from the area identified as potential overreach.

The drawing system accounts for images that are letterboxed within the interface. Pointer coordinates are mapped to the actual contained image rather than the entire surrounding panel, ensuring that clicks in the black bars do not affect the property boundary or proposed mask.

Geometry calculations, jurisdiction rules, and the four generated documents are covered by unit tests.

Challenges We Ran Into

Read-Only Privacy Configurations

The privacy-zone configuration endpoint allows Vicinal to inspect existing zones but not update them. The application therefore generates proposed masks in the same vertex structure returned by the API.

Applying a recommendation remains a manual step in the Ring app. This limitation is documented in the project's friction log.

Playground Snapshot Availability

Playground snapshots sometimes return 416 MEDIA_NOT_FOUND until a simulated Package, Vehicle, or Motion live view has run. This makes a predictable demo workflow more difficult.

Tokens also expire after approximately 30 minutes, and returned snapshots carry a watermark that cannot be removed.

Limited Location Information

The available location data contains a country and, in some cases, a state. This is enough to select a jurisdiction-specific audio rule, but it is not enough to infer a property boundary.

Vicinal deliberately leaves that boundary to the property owner rather than attempting to guess it.

Image Coordinate Mapping

One of the most time-consuming bugs involved drawing the property boundary on a letterboxed image. The initial canvas treated the entire panel as the image, causing traced points to drift away from the actual scene.

The coordinate mapping was corrected so that drawing, scoring, and mask generation all use the contained image dimensions.

Accomplishments We're Proud Of

  • Owner-defined boundaries: The property line comes from the person who knows the property, not an AI-generated guess.
  • Underused API capabilities: Vicinal combines location information, existing privacy-zone polygons, and camera stills into a practical privacy assessment.
  • Native coordinate output: Proposed masks use Ring's vertex format, making manual application straightforward.
  • Four generated documents: The neighbor notice, door sign, privacy record, and audio decision all derive from the same assessment.
  • Security-conscious token handling: The Playground token remains in process memory and is never written to disk.
  • Tested geometry and rules: Unit tests cover geometry calculations, jurisdiction logic, and document generation.

What We Learned

The most useful parts of a camera API are not always its most obvious features. A still image, coarse location data, and existing privacy-zone polygons can provide the building blocks for a meaningful privacy assessment.

We also learned that the right input for a property boundary is the property owner. A model can help calculate and visualize the implications of that boundary, but it should not invent one.

Finally, integrating with a partner API means respecting its operational constraints: short-lived tokens, image redirects, persistent watermarks, unavailable Playground media, and configurations that can be read but not written.

What's Next for Vicinal

  • Improve the friction log: Record actual HTTP status codes and responses observed during Playground sessions.
  • Strengthen the demo workflow: Capture a repeatable demonstration using a real device list and an available Ring still.
  • Publish the repository: Release the source code under the MIT License.
  • Support configuration writes: If Ring introduces an authorized configuration-write endpoint or a preview API for proposed privacy zones, integrate it so recommendations can be applied or previewed without manual copying.
  • Improve Playground reliability: A longer-lived token and a ready snapshot for each simulated scene would make demonstrations more reliable.

Security and Privacy

Vicinal is designed to minimize unnecessary exposure of credentials and to keep property boundaries under the owner's control.

  • The Playground token stays in process memory for the lifetime of the process.
  • The token is never written to disk.
  • Bearer credentials are not forwarded when following a pre-signed image URL to its image host.
  • Uploaded still images are explicitly labeled as not from Ring.
  • Property boundaries are manually defined by the owner rather than inferred from location metadata.

Use the application only with cameras and accounts you are authorized to access. Review any generated privacy or jurisdiction documents before relying on them.

Disclaimer

Vicinal is an experimental privacy-assessment tool. Its overreach score is an approximate, grid-based metric, and its generated documents are drafts for human review. It does not establish legal property boundaries, determine legal compliance, or provide legal advice.

License

Vicinal is intended to be released under the MIT License. The repository should include the corresponding LICENSE file before distribution.

Built With

Share this project:

Updates

Submission history