TrafficEye Largest Road User Reader

Use this skill when the user wants the largest detected vehicle from an image, along with its make and model classification and every detected license plate belonging to that same road user.

What This Skill Does

1. 1. Accepts a local image path.
2. Uploads the image to the TrafficEye recognition API.
3. Sends a recognition request that asks for detection, OCR, and MMR with box preference by default.
4. Parses the API response, including responses wrapped as { "status": ..., "data": ... }.
5. Picks the largest detected road user by box.position area.
6. Returns a wrapper object containing roadUser, box, plates, area, and source, preserving the full selected road-user payload.

Expected Input

• - A local image file path.
• If the user supplied an attachment instead of a path, first resolve it to a local file path and then run the helper.

Default Runtime Assumptions

• - The API endpoint defaults to https://trafficeye.ai/recognition.
• The default request payload is {"tasks":["DETECTION","OCR","MMR"],"requestedDetectionTypes":["BOX","PLATE"],"mmrPreference":"BOX"}.
• The default API-key transport matches the TrafficEye public API example: header mode with header name apikey.
• Auth and request fields remain configurable in case your deployment differs.

Environment Variables

• - TRAFFICEYE_API_KEY: required unless passed explicitly to the helper.
• INLINECODE11: optional, defaults to https://trafficeye.ai/recognition.
• INLINECODE13: one of header, bearer, form, query. Default: header.
• INLINECODE19: key name for header, form, or query mode. Default: apikey.
• INLINECODE24: multipart field for the image. Default: file.
• INLINECODE26: multipart field for the JSON request. Default: request.
• INLINECODE28: JSON string to include as the request field. By default this is {"tasks":["DETECTION","OCR","MMR"],"requestedDetectionTypes":["BOX","PLATE"],"mmrPreference":"BOX"}.
• INLINECODE30: optional timeout in seconds. Default: 30.

Only TRAFFICEYE_API_KEY is required for the default live API flow. The other variables are optional overrides.

How To Run

Setup your API key:
CODEBLOCK0

Use the road-user helper:

CODEBLOCK1

For structured output:

CODEBLOCK2

If the deployment expects Bearer auth:

CODEBLOCK3

If the deployment needs an explicit request payload:

CODEBLOCK4

Equivalent to the documented public API example:

CODEBLOCK5

Agent Workflow

1. 1. Verify that the image path exists.
2. Run python3 recognize_road_user.py <image-path> --format json.
3. Present the full selected road-user payload to the user, especially box, mmr, and the complete plates array.
4. If the selected road user has no plates, explain that the largest vehicle was found but no plates were attached to that road user.
5. If authentication fails, ask the user which auth mode their deployment expects and retry with the matching environment variables.

Offline Validation

You can validate the selection logic without calling the API:

CODEBLOCK6

Output Shape

The helper prints JSON with this top-level structure:

CODEBLOCK7

• - roadUser is the original selected road-user payload from TrafficEye.
• INLINECODE38 repeats roadUser.box for convenience.
• INLINECODE40 repeats roadUser.plates for convenience and may be empty.
• INLINECODE42 is the computed rectangle area used for winner selection.
• INLINECODE43 identifies where the selected road user came from in the API response.

Notes

• - The helper intentionally chooses the largest boxed vehicle by geometric area, not by detection confidence.
• The response parser first checks data.combinations[].roadUsers[], then combinations[].roadUsers[], then roadUsers[], and finally nested road-user payloads discovered recursively.
• The default request and auth header mirror the public example at https://www.trafficeye.ai/api.
• The selected result now includes the original road-user payload from the API so mmr, box, all plates, and their scores are preserved.