Applications - Edges
- 25 Oct 2024
- 14 Minutes to read
- Print
- DarkLight
Applications - Edges
- Updated on 25 Oct 2024
- 14 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
There are a variety of application edges which return a paginated list of application-specific objects.
Application Performance
Three application endpoints return performance statistics such as precision, recall, and F1 score for all previously released models calculated against different data sets.
All performance endpoints accept the same query arguments and return data in the same format.
Example Response
{
"data": [
{
"app_id": "app123",
"data_count": 849,
"loss": null,
"model_performance": {
"F1": 0.87,
"FN": 104,
"FP": 104,
"TN": 838,
"TP": 745,
"accuracy": 0.88,
"precision": 0.87,
"recall": 0.87
},
"model_performance_per_subject": {
"bicycle": {
"F1": 0.98,
"FN": 1,
"FP": 7,
"TN": 604,
"TP": 237,
"accuracy": 0.99,
"precision": 0.97,
"recall": 0.99
},
"bus": {
"F1": 0.98,
"FN": 15,
"FP": 4,
"TN": 684,
"TP": 146,
"accuracy": 0.99,
"precision": 0.97,
"recall": 0.99
},
"emergency_services": {
"F1": 0.83,
"FN": 9,
Release Validation Performance
Release Validation performance reports model performance scores tested against the validation data set at the time each model was released.
Endpoint
GET /1/applications/{application_id}/performance/releaseValidation
Host: https://api.cogniac.ioCurrent Validation Performance
Current Validation performance reports model performance scores tested against the current validation data set.
Endpoint
GET /1/applications/{application_id}/performance/currentValidation
Host: https://api.cogniac.ioNew Random Performance
New Random performance reports model performance against a set of data that each model has not encountered in either a test or validation set at the time of mode release.
Endpoint
GET /1/applications/{application_id}/performance/newRandom
Host: https://api.cogniac.ioApplication Detections
The Application Detections endpoint returns the latest assertions on media from either a user or the application's current best model.
The following query parameters are supported:
Argument | Example | Description |
|---|---|---|
start | 1234567890.0 | (optional) Unix timestamp. Return media updated after this timestamp. |
end | 1234567890.0 | (optional) Unix timestamp. Return media updated prior to this timestamp. |
probability_upper | 0.75 | (optional) Subject-media association probability ceiling. |
probability_lower | 0.25 | (optional) Subject-media association probability floor. |
limit | 10 | (optional) Number of results to return per page. |
reverse | True | (optional) True = return results in descending order based on assertion timestamp. False = return results in ascending order. |
consensus_none | 'True' | (optional) When set to True, will return only media assertions that have not reached consensus. |
only_user | True | (optional) When set to True, will return only media assertions made by users. |
only_model | False | (optional) When set to True, will return only media assertions made by the latest best model. |
Endpoint
GET /1/applications/{application_id}/detections
Host: https://api.cogniac.ioThis endpoint will return a list of the most recent assertions on media items that were processed by the application:
Example Response
{
"data": [
{
"detections": [
{
"app_data": null,
"app_data_type": null,
"app_id": "0Am1V3kr",
"created_at": 1497662139.841296,
"detection_id": "QMQYDAVPXP:0",
"focus": null,
"media_id": "XVLNY8FEKGT1VZC3XN2JGS2ZVAWH",
"model_id": "Hpo-d-6fa6-2Xg6MZdpxEC2Jvx3K1-YN_mtsv0_4782.tgz",
"prev_prob": null,
"probability": 0.001000835148309544,
"subject_uid": "cat_a1",
"uncal_prob": 0,
"user_id": null
}
],
"media": {
"author": null,
"author_profile_url": null,
"created_at": 1497662135.660577,
"external_media_id": null,
"filename": null,
"frame": null,
"image_height": 1200,
"image_width": 800,
"license": null,
"md5": "05180dac616104ff004027a5f274d6ad",
"media_format": "JPEG",
"media_id": "XVLNY8FEKGT1VZC3XN2JGS2ZVAWH",
"media_src": "twitter",
"media_timestamp": 1497662135.629489,
"media_url": "https://cogniac-media.s3.amazonaws.com/XVLNY8FEKGT1VZC3XN2JGS2ZVAWH",
"meta_tags": [
"twitter"
],
"network_camera_id": null,
"original_landing_url": null,
"original_url": null,
"parent_media_id": null,
"parent_media_ids": [],
"preview_url": null,
"resize_urls": {
"454": "https://cogniac-media.s3.amazonaws.com/XVLNY8FEKGT1VZC3XN2JGS2ZVAWH_max_454",
"750": "https://cogniac-media.s3.amazonaws.com/XVLNY8FEKGT1VZC3XN2JGS2ZVAWH_max_750"
},
"set_assignment": "training",
"size": 168423,
"source_url": null,
"status": "success",
"tenant_id": "skjdfh853k4jt",
"title": null,
"uploaded_by_user": null,
"video": false
},
"focus": {
"box": {
"x0": 50,
"x1": 275,
"y0": 634,
"y1": 870
}
},
"updated_at": 1497662139.841296
}
],
"paging": {
"next": "https://api.cogniac.io/1/applications/0Am1V3kr/detections?&end=1482263487.41&reverse=False&start=0&limit=5&only_user=False&only_model=False&probability_upper=1.0&probability_lower=0.0&cursor=1481857295.877328&consensus_none=False"
}
}
Application Detections (URL Callback)
In addition to polling for recent Application detections, you can also specify a callback URL to receive postback detections in realtime as they occur. Please enter your listening URL's in the detection_post_urls field of the Application object, for example "detection_post_urls":["http://127.0.0.1:9999/my_model_output.net", "https://product_model_detections.co"].
Posts are retried for thirty seconds, but URL's that fail retried posts after thirty seconds are blacklisted for five minutes.
Expected Callback Json
{
"media": {
"media_id": "dfc37db6723376ab953b10cd40097a68",
"parent_media_ids": ["c8ee0f4f05f3fdcf36f69a3fd81fd84f"]
},
"focus": {
"box": {
"x0": 50,
"x1": 275,
"y0": 634,
"y1": 870
}
},
"subjects": [
{
"subject_uid": "dog",
"probability": 0.79,
"updated_at": 1481857269.646634
},
{
"subject_uid": "cat",
"probability": 0.49,
"updated_at": 1481857269.646634
}
]
}
Application Feedback
Feedback is used to train and improve the performance of the Application. Feedback is a human task, where users can review predictions from an Application and correct any wrong predictions.
The Cogniac mobile app and web app have optimized feedback interface, and we advise users to utilize the existing interfaces for high-volume feedback tasks (particularly early during the training process).
Application's Pending Feedback Count
Query this endpoint to get the list of feedback requests that you want the user to provide feedback on.
Application's Pending Feedback
Endpoint
GET /1/applications/{application_id}/feedback?limit=5
Host: https://api.cogniac.ioSuccessful Response
[
{
"media": {
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"resize_urls": {},
"media_url": "https://cogniac-media.s3.amazonaws.com/eb51e7275210d74f5a0116e32c8b32d4"
},
"focus": {
"box": {
"x0": 50,
"x1": 275,
"y0": 634,
"y1": 870
}
},
"subjects": [
{
"app_data_type": null,
"subject_uid": "bill",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.9424338417689073,
"app_data": {}
},
{
"app_data_type": null,
"subject_uid": "prashant",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.01827074101387713,
"app_data": {}
},
{
"app_data_type": null,
"subject_uid": "amy",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.023146493553089783,
"app_data": {}
},
{
"app_data_type": null,
"subject_uid": "visitor",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.02874867741689087,
"app_data": {}
}
],
"media_id": "eb51e7275210d74f5a0116e32c8b32d4"
}
]
Provide Feedback
Endpoint
POST /1/applications/{application_id}/feedback
Host: https://api.cogniac.ioPOST Body
[
{
"media": {
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"resize_urls": {},
"media_url": "https://cogniac-media.s3.amazonaws.com/eb51e7275210d74f5a0116e32c8b32d4"
},
"focus": {
"box": {
"x0": 50,
"x1": 275,
"y0": 634,
"y1": 870
}
},
"subjects": [
{
"app_data_type": null,
"subject_uid": "bill",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.9424338417689073,
"app_data": {}
},
{
"app_data_type": null,
"subject_uid": "prashant",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.01827074101387713,
"app_data": {}
},
{
"app_data_type": null,
"subject_uid": "amy",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.023146493553089783,
"app_data": {}
},
{
"app_data_type": null,
"subject_uid": "visitor",
"media_id": "eb51e7275210d74f5a0116e32c8b32d4",
"probability": 0.02874867741689087,
"app_data": {}
}
],
"media_id": "eb51e7275210d74f5a0116e32c8b32d4"
}
]
Application-Specific Data
Subject-media associations have optional additional application-specific data relative to the subject, box region areas in detection applications, and range of frames in detection full-frame applications, etc.
The Cogniac system supports the following application data types:
box_set - A list of box regions corresponding to the subject. A box region is defined as:
{
“box”: (dictionary of integers) “x0”, “x1”, “y0”, “y1”
Values correspond to pixel offsets in the media item
(x0, y0) upper left corner of bounding box
(x1, y1) lower right corner of bounding box
Note that x1 must be greater than x0
and y1 must be greater than y0
<pre><code>“probability”: (optional) (float) probability for box
</code></pre>
Text}
segment_list - A list of video frame segments corresponding to the subject. A segment is defined as:
{
“segment”: (dictionary of integers) “f0”, “f1”
f0 & f1 correspond to the frame offsets in a video media
(frame count starts at 0)
f0 is the first frame in the media item segment with the subject
f1 is the last frame in the media item segment with the subject
Note that f1 must be greater than, or equal to f0
“probabilities”: [ordered list of per-frame model output probabilities]
The first list entry corresponds to prob for the frame at f0
The last list entry corresponds to prob for the frame at f1
Note the length of the list if present must equal (f1 - f0 + 1)
}
ocr - A string representing the characters detected.
7ZYA906
Application Feedback Semantics
Classification
Feedback Request
System proposes single most likely subject_uid associated with a full-frame media_id
Feedback
User supplies single most likely subject_uid associated with a media_id with result=True
result=False feedback is not allowed for classification applications.
result=Uncertain feedback is not currently supported for classification applications.
Detection Fullframe
Feedback Request
System proposes probability of association for each output subject_uid configured for an application
Feedback
User supplies “True”, “False”, or “Uncertain” for each output subject_uid configured for an application in a single feedback POST transaction.
Detection ROI
Feedback Request
System proposes single most likely region associated with the application’s subject_uid within a media_id.
Feedback
User supplies “True”, “False”, or “Uncertain” feedback result for the region proposed by the system. System immediately relays this “True”, “False”, or “Uncertain” via the POST feedback result API.
If user selects “False” or “Uncertain” feedback the user is always given the opportunity to correct the bounding box. This bounding box correction should only be enabled after the user selects “False” or “Uncertain” feedback result on the original proposal.
After a user provides False feedback on an original proposal and is given the option to correct the bounding box, the user can have the option of not providing a new bounding box (e.g. if the ROI does not exist in the image). In this case no additional feedback is required beyond the original False feedback.
If the bounding box is corrected that will be relayed to the system as a second feedback response with result True and appropriate bounding box coordinates.
Application Replay
The application replay endpoint allows users to resubmit, or "replay", media in the Cogniac System, that is readable by them, through an application for new detections.
The replay endpoint provides the user the ability to choose which subjects' associated media to replay through the application, not limited to the subjects bound to the application, as well as filters based on time and subject-media association probability.
Send Replay Request
To replay media through an application, POST a replay request message to the application replay endpoint with appropriate replay flags set.
The POST response contains a list of replaying subjects as well as a map of replay specifications for each subject.
Endpoint
POST /1/applications/{app_id}/replay
Host: https://api.cogniac.ioPOST Body
{
"replay": true,
"replay_subjects": ["cat_1a", "dog_2b"],
"replay_order": "random"
}
Successful Response
{
"replay": true,
"replay_subjects": ["cat_1a", "dog_2b"],
"replay_arguments": {
"cat_1a": {
"force_feedback": false,
"limit": null,
"probability_lower": 0.0,
"probability_upper": 1.0,
"replay_order": "random",
"replayed": 12
},
"dog_2b": {
"force_feedback": false,
"limit": null,
"probability_lower": 0.0,
"probability_upper": 1.0,
"replay_order": "random",
"replayed": 15
}
}
}
Get Replay Status
The current replay status of an application can be received via a GET call to the application replay endpoint.
Endpoint
GET /1/applications/{app_id}/replay
Host: https://api.cogniac.ioA successful response will return the boolean replay flag as well as a list of the subjects that are replaying media through the application.
Successful Response
{
"replay": true,
"replay_subjects": ["cat_1a"],
"replay_arguments": {
"cat_1a": {
"force_feedback": false,
"limit": null,
"probability_lower": 0.0,
"probability_upper": 1.0,
"replay_order": "random",
"replayed": 26
}
}
}
Stop Replaying Subjects
Any subject that is readable by the authorized tenant can have associated media replayed through an application, regardless of whether the subject is bound to the application.
In addition to starting, when stopping application replay the subject_uids of the replaying subjects must be passed. Prior to stopping application replay it is recommended to send a GET /1/applications/{app_id}/replay request to retrieve a list of subjects whose associated media is actively replaying.
Application Consensus History
The Application Consensus History returns subject-media consensus counts over time for the output subjects of the application.
Endpoint
GET /1/applications/{app_id}/consensusHistory
Host: https://api.cogniac.ioExample Repsonse
{
"data": [
{
"subjects": {
"cat": {
"True": 91
},
"dog": {
"False": 40
},
"bird": {
"True": 11
}
},
"timestamp": 1490986560
},
{
"subjects": {
"cat": {
"True": 82
},
"dog": {
"False": 20
}
},
"timestamp": 1490986620
}
]
}
Was this article helpful?