deepvision-sdk 0.1.1
DeepVision Python SDK makes face recognition into your application even easier.
Keywords: DeepVision,Computer Vision,SDK

# DeepVision Python SDK

DeepVision Python SDK makes product recognition into your application even easier.

# Table of content
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
  - [Initialization](#initialization)
  - [Adding products into a product collection](#adding-products-into-a-product-collection)
  - [Recognition](#recognition)
- [Reference](#reference)
  - [DeepVision Global Object](#deepvision-global-object)
    - [Methods](#methods)
  - [Product Recognition Service](#product-recognition-service)
    - [Recognize Products from a Given Image](#recognize-products-from-a-given-image)
    - [Get Product Collection](#get-product-collection)
      - [Add an Example of a Product](#add-an-example-of-a-product)
      - [List of All Saved Examples of the Product](#list-of-all-saved-examples-of-the-product)
      - [Delete All Examples of the Product by Name](#delete-all-examples-of-the-product-by-name)
      - [Delete an Example of the Product by ID](#delete-an-example-of-the-product-by-id)
      - [Verify Products from a Given Image](#verify-products-from-a-given-image)
    - [Get Products](#get-products)
      - [Add a Product](#add-a-product)
      - [List Products](#list-products)
      - [Rename a Product](#rename-a-product)
      - [Delete a Product](#delete-a-product)
      - [Delete All Products](#delete-all-products)
    - [Product Detection Service](#product-detection-service)
      - [Detect](#detect)
    - [Product Verification Service](#product-verification-service)
      - [Verify](#verify)

# Requirements

Before using our SDK make sure you have installed Python on your machine.
1. [Python](https://www.python.org/downloads/) (Version 3.7+)

## DeepVision compatibility matrix
Explanation:

* ✔  SDK supports all functionality from DeepVision. 


# Installation

It can be installed through pip:

```shell
pip install deepvision-sdk
```

# Usage

All these examples you can find in repository inside [examples](/examples) folder.

## Initialization

To start using Python SDK you need to import `DeepVision` object from 'deepvision-sdk' dependency.  

After you initialized `DeepVision` object you need to init the service object with the `api key` of your product service. You can use this service object to recognize products.

However, before recognizing you need first to add products into the product collection. To do this, get the product collection object from the service object.

```python
from deepvision import DeepVision
from deepvision.service import ProductRecognitionService
from deepvision.collections import ProductCollection
from deepvision.collections.product_collections import Products

DOMAIN: str = 'http://deepvision.ekgis.vn'
PORT: str = '2023'
API_KEY: str = 'your_api_key'

deep_vision: DeepVision = DeepVision(DOMAIN, PORT)

product_recognition: ProductRecognitionService = deep_vision.init_product_recognition(API_KEY)

product_collection: ProductCollection = product_recognition.get_product_collection()

products: Products = product_recognition.get_products()
```

## Adding products into a product collection

Here is example that shows how to add an image to your product collection from your file system:

```python
collection_name= 'example_collection'
product_id = 'c303282d-f2e6-46ca-a04a-35d3d873712d'
product_name = 'example'
image_path = ['./common/product_example.png']
image_id = ['bd65600d-8669-4903-8a14-af88203add38']

product_collection.add(collection_name=collection_name, product_id=product_id, product_name=product_name, image_path=image_path, image_id=image_id)
```

## Recognition

This code snippet shows how to recognize unknown product.

```python
collection_name: str = 'example_collection'
image_path = './common/product_example.png'

product_recognition.recognize(collection_name = collection_name, image_path=image_path)
```

# Reference

## DeepVision Global Object

Global DeepVision Object is used for initializing connection to DeepVision and setting default values.
Default values will be used in every service method if applicable.
If the option’s value is set in the global object and passed as a function argument then the function argument value will be used.

**Constructor:**

```DeepVision(domain, port)```

| Argument | Type   | Required | Notes                                     | 
| ---------| ------ | -------- | ----------------------------------------- | 
| url      | string | required | URL with protocol where DeepVision is located. E.g. `http://deepvision.ekgis.vn` |
| port     | string | required | DeepVision port. E.g. `2023` |

Example:

```python
from deepvision import DeepVision

DOMAIN: str = 'http://deepvision.ekgis.vn'
PORT: str = '2023'

deep_vision: DeepVision = DeepVision(domain=DOMAIN, port=PORT})
```

### Methods

1. ```DeepVision.init_product_recognition(api_key)```

Inits product recognition service object.

| Argument | Type   | Required | Notes                                     |
| ---------| ------ | -------- | ----------------------------------------- |
| api_key  | string | required | Product Recognition Api Key in UUID format    |

Example:

```python
from deepvision.service import ProductRecognitionService

PRODUCT_RECOGNITION_API_KEY: str = 'your_api_key'

product_recognition: ProductRecognitionService = deep_vision.init_product_recognition(PRODUCT_RECOGNITION_API_KEY)
```

2. ```DeepVision.init_product_detection(api_key)```

Inits product detection service object.

| Argument | Type   | Required | Notes                                     |
| ---------| ------ | -------- | ----------------------------------------- |
| api_key  | string | required | Product Detection Api Key in UUID format    |

Example:

```python
from deepvision.service import ProductDetectionService

PRODUCT_DETECTION_API_KEY: str = 'your_product_detection_key'

product_detection: ProductDetectionService = deep_vision.init_product_detection(PRODUCT_DETECTION_API_KEY)
```

3. ```DeepVision.init_product_verification(api_key)```

Inits product verification service object.

| Argument | Type   | Required | Notes                                     |
| ---------| ------ | -------- | ----------------------------------------- |
| api_key  | string | required | Product Verification Api Key in UUID format    |

Example:

```python
from deepvision.service import ProductVerificationService

PRODUCT_VERIFICATION_API_KEY: str = 'your_api_key'

product_verify: ProductVerificationService = deep_vision.init_product_verification(PRODUCT_VERIFICATION_API_KEY)
```

Example of product recognition with object:

```python
product_recognition.recognize(collection_name=collection_name, image_path=image_path)
```

## Product Recognition Service

Product recognition service is used for product identification.
This means that you first need to upload known products to product collection and then recognize unknown products among them.
When you upload an unknown product, the service returns the most similar products to it.
Also, product recognition service supports verify endpoint to check if this person from product collection is the correct one.

### Recognize Products from a Given Image

*[Example](examples/recognize_product_from_image.py)*

Recognizes all products from the image.
The first argument is the image location, it can be an url, local path or bytes.

```python
product_recognition.recognize(collection_name=collection_name, image_path=image_path)
```

| Argument           | Type    | Required | Notes                                                                                                                                          |
| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| collection_name    | collection_name  | required | Collection contains sample products.  |
| image_path         | image   | required | Image can pass from url, local path or bytes. Max size is 5Mb                                                         |

Response:

```json
{
    'status': 'completed',
    'result': {
        'embedding': [-0.03902999835598629, "...", -0.028654199455642616],
        'bbox': [
            0, 0, 624, 773],
        'products': {
            'similarity': 0.9999999999999998,
            'product': 'test'
        }
    }
}
```

| Element                    | Type    | Description                                                                                                                                                 |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status                     | string   | status of the recognize operation.                                                   |
| embedding                  | array   | product embeddings.                                                   |
| bbox                        | array  | list of parameters of the bounding box for this product                                                                                                        |
| products                   | list    | list of similar products with size of <prediction_count> order by similarity                                                                                |
| similarity                 | float   | similarity that on that image predicted person                                                                                                              |
| product                    | string  | name of the product in Product Collection                                                                                                                      |

### Get Product Collection

```python
product_recognition.get_product_collection()
```

Returns Product collection object

Product collection could be used to manage known products, e.g. add, list, or delete them.

Product recognition is performed for the saved known products in product collection, so before using the `recognize` method you need to save at least one product into the product collection.

**Methods:**

#### Add an Example of a Product

*[Example](examples/add_example_of_a_product.py)*

This creates an example of the product by saving images. You can add as many images as you want to train the system. Image should
contain only one product.

```python
product_collection.add(collection_name, image_id, image_path, product_id, product_name)
```

| Argument           | Type   | Required | Notes                                                                                                |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| collection_name    | collection_name  | required | Collection contains sample products.  |
| image_id         | UUID  | required |  UUID of uploaded image               |
| image_path         | image  | required | Image can pass from url, local path or bytes. Max size is 5Mb               |
| product_id            | string | required | UUID of the saved product                                                         |
| product_name          | string | required | is the name you assign to the product you save                                                         |

Response:

```json
{
    'status': 'completed',
    'result':
    {
        'product_id': 'c303282d-f2e6-46ca-a04a-35d3d873712d',
        'product_name': 'example',
        'image_id': 'bd65600d-8669-4903-8a14-af88203add38'
    }
}
```

| Element  | Type   | Description                |
| -------- | ------ | -------------------------- |
| status   | string | status of the add operationt.  |
| product_id  | UUID | UUID of the saved product |
| product_name  | string | Name of the saved product |
| image_id | UUID   | UUID of uploaded image     |

#### List of All Saved Examples of the Product

To retrieve a list of products saved in a Product Collection:

```python
product_collection.list()
```

| Argument           | Type   | Required | Notes                                                                                                |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| collection_name    | collection_name  | required | Collection contains sample products.  |

Response:

```
{
    'status': 'completed',
    'result': [
        {
            'image_id': '938352ea-d744-4752-9ee8-0c73e9f55942',
            'product_id': '4371bb18-2a36-428b-92c2-da2e974168af',
            'product_name': 'example'
        },
        ...
    ]
}
```

| Element  | Type   | Description                |
| -------- | ------ | -------------------------- |
| status   | string | status of the list operation.  |
| product_id  | UUID | UUID of the saved product |
| product_name  | string | <product> of the product, whose picture was saved for this api key |
| image_id | UUID   | UUID of uploaded image     |



#### Delete All Examples of the Product by Name

*[Example](examples/delete_all_examples_of_product.py)*

To delete all image examples of the <product>:

```python
product_collection.delete_all(collection_name, product_name)
```

| Argument  | Type   | Required | Notes                                                                                                                                |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| collection_name    | collection_name  | required | Collection contains sample products.  |
| product_name   | string | optional | is the name you assign to the image you save. |

Response:

```
{
    'status': 'completed',
    'result':
    {
        'deleted': <count>
    }
}
```

| Element  | Type    | Description              |
| -------- | ------- | ------------------------ |
| status   | string | status of the delete operation .  |
| deleted  | integer | Number of deleted examples  |

#### Delete an Example of the Product by ID

*[Example](examples/delete_example_by_id.py)*

To delete an image by ID:

```python
product_collection.delete(collection_name, image_id)
```
| Argument  | Type   | Required | Notes                                                        |
| --------- | ------ | -------- | ------------------------------------------------------------ 
| collection_name    | collection_name  | required | Collection contains sample products.  |
| image_id  | UUID   | required | UUID of the removing product                                    |

Response:

```
{
    'status': 'completed',
    'result':
    {
        'image_id': <removed_image_id>
    }
}
```

| Element  | Type   | Description                                                       |
| -------- | ------ | ----------------------------------------------------------------- |
| status   | string | status of the delete operation.  |
| image_id | UUID   | UUID of the removed product                                          |

#### Verify Products from a Given Image

*[Example](examples/verification_product_from_image.py)*

```python
product_collection.verify(collection_name, image_path, product_name)
```

Compares similarities of given image with image from your product collection.


| Argument           | Type    | Required | Notes                                                                                                                                                 |
| ------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| collection_name    | collection_name  | required | Collection contains sample products.  |
| image_path         | image   | required | Image can pass from url, local path or bytes. Max size is 5Mb                                                                |
| product_id           | UUID    | required | UUID of the verifying product                                                                                                                            |

Response:

```json
{
    'status': 'completed',
    'result':
    {
        'verify': 'True',
        'product': 'test',
        'embedding': [-0.03902999835598629, "...", -0.028654199455642616],
        'bbox': [0, 0, 624, 773]
    }
}
```

| Element                        | Type    | Description                                                  |
| ------------------------------ | ------- | ------------------------------------------------------------ |
| status   | string | status of the verify operation. |
| verify   | Boolean | result of the verify operation. |
| embedding                      | array   | product embeddings.      |
| bbox                            | object  | list of parameters of the bounding box for this product         |

### Get Products

```python
product_recognition.get_products()
```

Returns products object

Products object allows working with products directly (not via product examples).

More information about products [here](https://bugs.ekgis.vn/deepvision)

**Methods:**

#### Add a Product

*[Example](examples/add_product.py)*

Create a new product in Product Collection.
```python
products.add(collection_name, product_id, product_name, image_paths, image_ids)
```

| Argument           | Type   | Required | Notes                                                                   |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------|
| collection_name    | collection_name  | required | Collection contains sample products.  |
| image_ids        | UUID  | required |  List UUID of uploaded image               |
| image_paths         | image  | required | List image can pass from url, local path or bytes.              |
| product_id            | string | required | UUID of the saved product                                                         |
| product_name          | string | required | is the name you assign to the product you save                                               |

Response:

```json
{
    "status": 'completed',
    'result':
    {
        "image_id": <image_ids>,
        "product_id": <product_id>,
        "product_name": <product_name>
    }
}
```

| Element  | Type   | Description                |
| -------- | ------ | -------------------------- |
| status   | string | status of the add operationt.  |
| product_id  | UUID | UUID of the saved product |
| product_name  | string | Name of the saved product |
| image_id | UUID   | UUID of uploaded image     |

#### List Products

*[Example](examples/get_list_of_all_products.py)*

Returns all product related to Product Collection.
```python
products.list(collection_name=collection_name)
```

Response:

```json
{
    'status': 'completed',
    'result':
    [
        {'product_id': '123', 'product_name': 'test'},
        ...
    ]
}

```

| Element  | Type   | Description                |
| -------- | ------ | -------------------------- |
| status   | string | status of the list operationt.  |
| product_id  | UUID | UUID of the saved product |
| product_name  | string | Name of the saved product |

#### Rename a Product

*[Example](examples/update_existing_product.py)*

Rename existing product. If a new product name already exists, products are merged - all products from the old product name are reassigned to the product with the new name, old product removed.

```python
products.rename(collection_name, product_id, new_name)
```

| Argument            | Type   | Required | Notes                                                                   |
| ------------------  | ------ | -------- | ------------------------------------------------------------------------|
| collection_name    | collection_name  | required | Collection contains sample products.  |
| product_id             | string | required | is the UUID of the product that will be updated                         |
| new_name            | string | required | is the name of the product. It can be any string                        |

Response:

```json
{
    'status': 'completed',
    'result':
    {
        "updated": "true|false"
    }
}
```

| Element  | Type    | Description                |
| -------- | ------  | -------------------------- |
| status   | string | status of the update operationt.  |
| updated  | boolean | failed or success          |

#### Delete a Product

*[Example](examples/delete_product_by_id.py)*

Delete existing product and all saved products by id.
```python
products.delete_product_by_id(collection_name, product_id)
```

| Argument           | Type   | Required | Notes                                                                   |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------|
| collection_name    | collection_name  | required | Collection contains sample products.  |
| product_id            | string | required | is the name of the product.                                             |

Response:

```json
{
    'status': 'completed',
    'result':
    {
        'product_id': <remove_id>
    }
}
```

| Element  | Type   | Description                |
| -------- | ------ | -------------------------- |
| status   | string | status of the remove operationt.  |
| product_id  | string | is the id of removed product |


*[Example](examples/delete_product_by_name.py)*

Delete existing product and all saved products by name.
```python
products.delete_product_by_name(collection_name, product_name)
```

| Argument           | Type   | Required | Notes                                                                   |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------|
| collection_name    | collection_name  | required | Collection contains sample products.  |
| product_name            | string | required | is the name of the product.                                             |

Response:

```json
{
    'status': 'completed',
    'result':
    {
        'product_name': <remove_name>
    }
}
```

| Element  | Type   | Description                |
| -------- | ------ | -------------------------- |
| status   | string | status of the remove operationt.  |
| product  | string | is the name of the product |

#### Delete All Products

*[Example](examples/delete_all_products.py)*

Delete all existing products and all saved products.
```python
products.delete_all(collection_name)
```

| Argument           | Type   | Required | Notes                                                                   |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------|
| collection_name    | collection_name  | required | Collection contains sample products.  |

Response:

```json
{
    'status': 'completed',
    'result':
    {
        'deleted': <count>
    }
}
```

| Element  | Type    | Description              |
| -------- | ------- | ------------------------ |
| status   | string | status of the delete operation .  |
| deleted  | integer | Number of deleted products  |


## Product Detection Service

Product detection service is used for detecting products in the image.

**Methods:**

### Detect

*[Example](examples/detect_product_from_image.py)*

```python
product_detection.detect(image_path)
```

Finds all products on the image.

| Argument          | Type    | Required | Notes                                                                                                                                          |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| image_path        | image   | required | image where to detect products. Image can pass from url, local path or bytes. Max size is 5Mb                            |


Response:

```json
{
    'status': '1',
    'locates':
    [
        {'label': 'product', 'score': 0.959, 'bbox': [193, 160, 379, 363]},
        "...",
        {'label': 'product', 'score': 0.563, 'bbox': [233, 754, 323, 772]}
    ]
}}
```

| Element                        | Type    | Description                                                  |
| ------------------------------ | ------- | ------------------------------------------------------------ |
| status   | string | status of the delete operation .  |
| bbox                            | array  | list of parameters of the bounding box for this product (on processedImage) |
| label                    | string   | Label detection     |


## Product Verification Service

*[Example](examples/verify_product_from_image.py)*

Product verification service is used for comparing two images.
A source image should contain only one product which will be compared to all products on the target image.

**Methods:**

### Verify

```python
product_verify.verify(source_image_path, target_image_path)
```

Compares two images provided in arguments. Source image should contain only one product, it will be compared to all products in the target image.

| Argument            | Type    | Required | Notes                                                                                                                                                 |
| ------------------  | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| source_image_path   | image   | required | file to be verified. Image can pass from url, local path or bytes. Max size is 5Mb                                           |
| target_image_path   | image   | required | reference file to check the source file. Image can pass from url, local path or bytes. Max size is 5Mb                       |

Response:

```json
{
    'status': 'completed',
    'result': {
        'source_image_product':
        {
            'embedding': [-0.03902999835598629, '...', -0.028654199455642616],
            'bbox': [0, 0, 624, 773]
        },
            'product_matches':
            {
                'embedding': [-0.03902999835598629, '...', 5, -0.028654199455642616],
                'bbox': [0, 0, 624, 773],
                'verify': 'True',
                'similarity': array([[0.]])
        }
    }
}
```

| Element                        | Type    | Description                                                  |
| ------------------------------ | ------- | ------------------------------------------------------------ |
| source_image_product              | object  | additional info about source image product |
| product_matches                   | array   | result of product verification |
| embedding                      | array   | product embeddings.       |
| box                            | object  | list of parameters of the bounding box for this product         |
| verify  | boolean | failed or success          |
| similarity                     | float   | similarity between this product and the product on the source image               |