Grace Vision for GraceWays Animals

OpenCV-powered photo triage for animal shelters: measurable quality, conservative improvement, and human approval without inventing an animal's appearance.

Comment

Grace Vision for GraceWays Animals

OpenCV-powered photo triage for animal shelters: measurable quality, conservative improvement, and human approval without inventing an animal's appearance.

Inspiration

Animal shelters often have only a few photos to introduce an animal to potential adopters. Those photos may be dark, blurred, poorly framed, or simply missing reliable visual information. A generic generative editor is the wrong tool for this setting: coat markings, body shape, injuries, and other identifying details must not be invented or changed.

Grace Vision is a bounded, explainable photo-review assistant for GraceWays Animals. It measures what is present, preserves every original, makes only conservative deterministic corrections, and gives the final decision to a person.

What it does

A shelter reviewer can submit one to five rights-cleared JPEG or PNG photos. Grace Vision then:

  1. preserves the original bytes and SHA-256;
  2. measures resolution, sharpness, brightness, contrast, dark-pixel share, and clipped highlights with OpenCV 5;
  3. uses OpenCV DNN with a pinned YOLOX-S model to produce cat-framing evidence, including confidence, bounding box, relative area, centering, and edge contact;
  4. selects a traceable next action: ACCEPT_ORIGINAL, ENHANCE, TRY_NEXT_IMAGE, or REQUEST_NEW_PHOTO;
  5. when safe, applies only modest brightness/contrast correction, denoising, limited sharpening, and a conservative crop, then measures the derivative again;
  6. displays the original, proposal, measurements, reasons, and decision trace; and
  7. requires explicit human visibility review and approval before the selected demo image can change.

Approval does not publish externally or write into production GraceWays Animals records. Grace Vision never uses inpainting, generative reconstruction, coat alteration, or body reshaping. If reliable information is missing, it requests another photo instead of fabricating detail.

How we built it

OpenCV 5.0.0 performs image decoding, technical measurements, deterministic correction, remeasurement, and DNN inference. A pinned OpenCV Zoo YOLOX-S model runs through cv2.dnn on CPU.

The material image workflow runs on AWS in eu-central-1:

  • an AWS Lambda container executes OpenCV 5.0.0;
  • a private Amazon S3 bucket keeps immutable originals and separate derivatives, blocks public access, uses AES-256 encryption, and deletes competition objects after seven days;
  • Amazon API Gateway exposes only the bounded create, analyze, result, and decide operations;
  • reserved concurrency, rate limits, and a daily request quota constrain the public demo.

A separate Cloudflare Worker acts as the public security boundary. It keeps the AWS API key and storage details out of the browser, validates Turnstile and CSRF, and issues short-lived session and job capabilities. The competition copy is deliberately isolated from the productive GraceWays Animals application.

Why OpenCV is essential

The recommendation is derived from actual image evidence, not an unsupported AI statement. OpenCV calculates:

  • image dimensions;
  • Laplacian-variance sharpness;
  • mean brightness;
  • contrast;
  • dark and overexposed pixel fractions;
  • YOLOX cat detection through OpenCV DNN;
  • bounding-box area, center offset, and edge contact; and
  • the same quality measurements after a derivative is created.

These values directly drive the next action and remain visible to the reviewer.

Agentic Vision workflow

Grace Vision implements a bounded perception-decision-action loop:

OpenCV evidence Next action
Quality and framing pass ACCEPT_ORIGINAL for human review
Correctable technical issue ENHANCE, then remeasure
A better candidate remains TRY_NEXT_IMAGE
Information is missing or unusable REQUEST_NEW_PHOTO
Any proposed main image Require explicit human approval

Visual evidence changes what the system does next. The decision trace records the measurements, reasons, chosen action, optional transformation, remeasurement, and final human decision. The system cannot publish autonomously.

Evaluation

We separate synthetic control cases from real-photo evidence.

Reproducible AWS control scenarios

Scenario Observed action Safety behavior
Suitable input ACCEPT_ORIGINAL No derivative
Correctable input ENHANCE Derivative remeasured before review
Unusable input REQUEST_NEW_PHOTO No reconstruction

In the recorded correctable control, resolution remained 800 x 640 pixels; brightness increased from 82.132 to 94.306, sharpness from 7610.638 to 8299.301, and contrast from 43.468 to 45.392. Original and derivative hashes were confirmed. The selected demo image changed only after approval.

Real-cat boundary case

A real-cat test photo of Molly produced an 86.8% cat confidence and a bounding box covering 77.9% of the frame. The photo had technically correctable darkness and slight blur, but the strict edge-contact policy returned REQUEST_NEW_PHOTO. We report this as a false rejection and a known calibration limitation. Molly's image was not approved or published. Its use in any submitted material remains conditional on explicit rights confirmation.

Engineering verification

The Phase 4H release passed 358 tests and 437 browser assertions. A later local session-renewal change passed 107 targeted adapter, Worker, and security checks but is not claimed as deployed in the public release.

This is a small engineering evaluation, not a calibrated accuracy study. We do not infer population-level performance from it.

Challenges

  • Preserving immutable originals while showing a verified derivative.
  • Keeping signed storage URLs, cloud identifiers, and credentials out of the browser.
  • Making CSRF, Turnstile, expiring sessions, and one-time decisions fail clearly without silent retries.
  • Separating technical image quality from suitability for an adoption listing.
  • Running OpenCV 5 and a pinned DNN detector reproducibly in Lambda.
  • Making conservative framing decisions without claiming that a detector proves identity, anatomy, or complete visibility.

Accomplishments

  • OpenCV 5.0.0 runs in the deployed AWS Lambda container.
  • AWS processing demonstrated accept, enhance, and request-new-photo control paths.
  • Original and derivative hashes were verified end to end.
  • One-photo and multi-photo jobs are supported.
  • Human approval is enforced before the demo's selected image changes.
  • Private storage, short-lived access, encryption, and seven-day retention are active.
  • A real-photo false rejection is documented rather than hidden.

Responsible use and limitations

  • The detector does not establish animal identity.
  • A bounding box does not prove that anatomy, injuries, occlusion, or coat markings are fully visible.
  • The strict edge-contact policy can reject otherwise useful photos.
  • Real-photo evaluation remains small.
  • The public demo accepts JPEG/PNG files up to 2 MiB and 1600 x 1600 pixels.
  • The jury demo does not publish images or persist approvals as productive GraceWays records.
  • The service is intentionally quota-limited and the USD 5 budget is an alert, not a hard cost cap.
  • The current container scan had 0 Critical findings and 7 High findings covered by a documented, time-limited manufacturer "Pending Fix" risk acceptance. We do not claim that the image is vulnerability-free.

What we learned

Explainable measurements and hashes make image assistance more trustworthy than a single unexplained score. Conservative failure is preferable to invented visual detail, but conservative thresholds still require real-world calibration. Human review is not an afterthought in Grace Vision; it is part of the system architecture.

What's next

  1. Expand the rights-cleared real-cat evaluation set.
  2. Refine edge-contact handling so it can block unsafe cropping without blocking safe global correction.
  3. Validate thresholds with animal-welfare users.
  4. Deploy and verify the locally tested session-renewal update.
  5. Add an optional authenticated GraceWays Animals integration only after a separate production security review.

Built with

OpenCV 5, Python, OpenCV DNN, YOLOX-S, AWS Lambda, Amazon S3, Amazon API Gateway, Amazon ECR, CloudFormation, Cloudflare Workers, Turnstile, JavaScript, HTML, CSS, Docker

Built With

Share this project:

Updates

Submission history