diff --git a/README.md b/README.md index 5d53ac9..ed59dd0 100644 --- a/README.md +++ b/README.md @@ -3,41 +3,136 @@ Module of the Viam vision service to automatically build, deploy, and run infere Internally, this module calls DirectAI's `deploy_detector` and `deploy_classifier` endpoints with the provided configuration, saves the ID of the deployed models, and then calls the models via their IDs on incoming images. See [docs](https://api.alpha.directai.io/docs) for an overview of DirectAI's publicly available API. -## Getting started +Note that this README closely follows Viam's in-house motion-detector documentation, as described [here](https://github.com/viam-labs/motion-detector/). -The first step is to obtain DirectAI API credentials. Instructions [here](https://api.alpha.directai.io/docs). - -This module implements the following methods of the [vision service API](https://docs.viam.com/services/vision/#api): - * `GetDetections()` - * `GetDetectionsFromCamera()` - * `GetClassifications()` - * `GetClassificationsFromCamera()` +## Getting started with Viam & DirectAI +Start by [configuring a camera](https://docs.viam.com/components/camera/webcam/) on your robot. Remember the name you give to the camera, it will be important later. > [!NOTE] > Before configuring your vision service, you must [create a robot](https://docs.viam.com/manage/fleet/robots/#add-a-new-robot). +Before calling DirectAI's API via Viam, you have to grab your client credentials. Generate them by clicking **Get API Access** on the [DirectAI website](https://directai.io/). Save them in an Access JSON on the same machine that's running your Viam Server. +```json +{ + "DIRECTAI_CLIENT_ID": "UE9S0AG9KS4F3", + "DIRECTAI_CLIENT_SECRET": "L23LKkl0d5 [!NOTE] -> For more information, see [Configure a Robot](https://docs.viam.com/manage/configuration/). ### Attributes The following attributes are available for `directai:viamintegration:directai-beta` vision services: +| Name | Type | Inclusion | Description | +|------|------|-----------|-------------| +| `access_json` | string | **Required** | A string that indicates an absolute path on your local machine to a JSON including DirectAI Client Credentials. See description in [Example Access JSON](#example-access-json) section. | +| `deployed_classifier` | json | **Optional** | A JSON that contains a `classifier_configs` key and corresponding list of classifier configurations. Each classifier is defined by a `name`, a list of text `examples_to_include`, and a list of text `examples_to_exclude`. See [Example Classifier Attributes](#example-classifier-attributes). | +| `deployed_detector` | json | **Optional** | A JSON that contains `detector_configs` (list of detector configurations) and an `nms_threshold`. Each detector is defined by a `name`, a list of text `examples_to_include`, a list of text `examples_to_exclude`, and a `detection_threshold`. For more information on NMS and Detection thresholds, check out the [DirectAI docs](https://api.alpha.directai.io/docs#/). See [Example Detector Attributes](#example-detector-attributes). | + +> [!NOTE] +> For more information, see [Configure a Robot](https://docs.viam.com/manage/configuration/). -### TODO: add overview of attributes +## Usage + +This module implements the following methods of the [vision service API](https://docs.viam.com/services/vision/#api): + * `GetDetections()` + * `GetDetectionsFromCamera()` + * `GetClassifications()` + * `GetClassificationsFromCamera()` -### Example Access JSON +The module behavior differs slightly for classifications and detections. +When returning classifications, the module will return a list of dictionaries. The list length will be equal to length of the `classifier_configs` list provided in the deployed classifier attributes. Each dictionary will include `class_name` and `confidence` key-value pair in decreaising confidence order. + +When returning detections, the module will return a list of detections with bounding boxes that encapsulate the movement. Each detection will be of the following form: ```json { - "DIRECTAI_CLIENT_ID": "UE9S0AG9KS4F3", - "DIRECTAI_CLIENT_SECRET": "L23LKkl0d5