# Ximilar API Python Client
This Python 3.9+ Client library is lightweight wrapper for `ximilar.com`.
## Installation
PyPI - (https://pypi.org/project/ximilar-client/):
# we recommend to install ximilar-client to new virtualenv
pip install ximilar-client
Manual installation with latest changes:
1. Cloning the repo
git clone https://gitlab.com/ximilar-public/ximilar-client.git
2. Install it with pip to your virtualenv
pip install -e ximilar-client
This will install also urllib3, requests, tqdm and pytest library. This will not install python-opencv which is required if you want to upload local images to the Ximilar system. For more information about installing opencv on different systems we have a small page in our [docs](https://docs.ximilar.com/quickstart/client_opencv/).
***You will need to install one of opencv-python or opencv-contrib-python (or headless) manually.***
## Usage
First you need to register via `app.ximilar.com` and obtain your `API TOKEN` for communication with ximilar rest endpoints. You can obtain the token from the [Ximilar App](https://app.ximilar.com/) at your profile page.
After you obtain the token, the usage is quite straightforward. First, import this package and create specific rest client (reconition/vize, tagging, colors, search, ...). In following example we will create client for `Ximilar Recognition Service` (vize.ai). For all other Ximilar Services as Tagging, Custom Object Detection you will need to contact `tech@ximilar.com` first, so they will provide you access to the service:
```python
from ximilar.client import RecognitionClient, DetectionClient
from ximilar.client import DominantColorProductClient, DominantColorGenericClient
from ximilar.client import FashionTaggingClient, GenericTaggingClient
app_client = RecognitionClient(token="__API_TOKEN__")
detect_client = DetectionClient(token="__API_TOKEN__")
...
```
## Workspaces
With a new version of Ximilar App you are able to work also with workspaces. Workspaces are entities where all your task, labels and images live. Each user has by default workspace with name `Default` (it will be used if you do not specify workspace when working with Image, Label, Task). However you can specify id of workspace in the constructor.
```python
client = RecognitionClient(token="__API_TOKEN__", workspace='__UUID_OF_YOUR_WORKSPACE__')
client = DetectionClient(token="__API_TOKEN__", workspace='__UUID_OF_YOUR_WORKSPACE__')
```
## Ximilar Recognition
This client allows you to work with Ximilar Recognition Service. With this client you are able to create classification or tagging tasks based on latest trends in machine learning and neural networks.
After creating client object you can for example load your existing task and call train:
```python
task, status = client.get_task(task_id='__ID_TASK_')
# Every label in the task must have at least 20 images before training.
# The training can take up to several hours as we are trying to achieve really high quality
# solution. This endpoint will immediately return success if your task is in training queue.
task.train()
# or you can list all your available tasks
tasks, status = client.get_all_tasks()
# or you can create new classification task
# each Task, Image, Label is identified by unique ID
task, status = client.create_task('__TASK_NAME__')
```
#### Task
Currently there are two types of task to create. User can select 'multi_class' (default) or 'multi_label'. See ximilar.docs for more info.
```python
# categorization/classification or multi class task means that image is assigned to exactly one label
# labels are exclusive which means image can contain only 'cat' or only 'dog'
classification_task, status = client.create_task('__TASK_NAME__')
# tagging or multi label task means that image can have one or more labels
# for example image can contain 'cat', 'dog' and 'animal' labels if there are on the picture
tagging_task, status = client.create_task('__TASK_NAME__', type='multi_label')
# removing task is possible through client object or task itself
client.remove_task(task.id)
task.remove()
```
#### Classify
Suppose you want to use the task to predict the result on your images. Please, always try to send image bigger than 200px and lower than 600px for quality and speed:
```python
# you can send image in _file, _url or _base64 format
# the _file format is intenally converted to _base64 as rgb image
result = task.classify([{'_url': '__URL_PATH_TO_IMG__'}, {'_file', '__LOCAL_FILE_PATH__'}, {'_base64': '__BASE64_DATA__'}])
# the result is in json/dictionary format and you can access it in following way:
best_label = result['records'][0]['best_label']
```
#### Labels
Labels are connected to the task. Depends which task you are working with (Tagging/multi_label or Categorization/multi_class) you can create Tag or Category labels. Working with the labels are pretty simple:
```python
# getting existing label
existing_label, status = client.get_label('__ID_LABEL__')
# creating new label (CATEGORY, which is default) and attaching it to existing Categorization task (multi class)
label, status = client.create_label(name='__NEW_LABEL_NAME__')
task.add_label(label.id)
# creating new label (TAG) for Tagging task (multi label)
label, status = client.create_label(name='__NEW_LABEL_NAME__', label_type='tag')
# get all labels which are connected to the task
labels, status = task.get_labels()
for label in labels:
print(label.id, label.name)
# get label with exact name which is also connected to specific task
label, status = task.get_label_by_name(name='__LABEL_NAME__')
# detaching (not deleting) existing label from existing task
task.detach_label(label.id)
# remove label (which also detach label from all tasks)
client.remove_label(label.id)
# detach image from label
label.detach_image(image.id)
# search labels which contains given substring in name
labels, status = client.get_labels_by_substring('__LABEL_NAME__')
```
#### Working with training images
Image is main entity in Ximilar system. Every image can have multiple labels (Recognition service) or multiple objects (Detection service).
```python
# getting all images of label (paginated result)
images, next_page, status = label.get_training_images()
while images:
for image in images:
print(str(image.id))
if not next_page:
break
images, next_page, status = label.get_training_images(next_page)
# basic operations
image, status = client.get_image(image_id=image.id)
image.add_label(label.id)
# detach label from image
image.detach_label(label.id)
# deleting image
client.remove_image(image.id)
```
Let's say you want to upload a training image and add several labels to this image:
```python
images, status = client.upload_images([{'_url': '__URL_PATH_TO_IMAGE__', 'labels': [label.id for label in labels], "meta_data": {"field": "key"}},
{'_file': '__LOCAL_FILE_PATH__', 'labels': [label.id for label in labels]},
{'_base64': '__BASE64_DATA__', 'labels': [label.id for label in labels]}])
# and maybe add another label to the first image
images[0].add_label("__SOME_LABEL_ID__")
```
Upload image without resizing it (for example Custom Object Detection requires high resolution images):
```python
images, status = client.upload_images([{'_url': '__URL_PATH_TO_IMAGE__', "noresize": True}])
```
Every image can have some meta data stored:
```python
image.add_meta_data({"__KEY_1__": "value", "__KEY_2__": {"THIS CAB BE":"COMPLEX"}})
image.clear_meta_data()
```
Every image can be marked with **test** flag (for evaluation on independent test dataset only):
```python
image.set_test(True)
```
Every image can be marked as real (default) or product. Product image should be images where is dominant one object on nice solid background. We can do more augmentations on these images.
```python
image.set_real(False) # will mark image as product
```
## Ximilar Flows
The client is able to get flow of the json or process images/records by the flow.
```python
from ximilar.client import FlowsClient
client = FlowsClient("__API_TOKEN__")
# get flow
flow, _ = client.get_flow("__FLOW_ID__")
# two way to call the flow on records
client.process_flow(flow.id, records)
flow.proces(records)
```
## Ximilar Object Detection
Ximilar Object Detection is service which will help you find exact location (Bounding Box/Object with four coordinates xmin, ymin, xmax, ymax).
In similar way as Ximilar Recognition, here we also have Tasks, Labels and Images. However one more entity called Object is present in Ximilar Object Detection.
First you need to create/get Detection Task:
```python
client = DetectionClient("__API_TOKEN__")
detection_task, status = client.create_task("__DETECTION_TASK_NAME__")
detection_task, status = client.get_task(task.id)
```
Second you need to create Detection Label and connect it to the task:
```python
detection_label, status = client.create_label("__DETECTION_LABEL_NAME__")
detection_label, status = client.get_label("__DETECTION_LABEL_ID__")
detection_task.add_label(detection_label.id)
```
Lastly you need to create Objects/Bounding box annotations of some type (Label) on the images:
```python
image, status = client.get_image("__IMAGE_ID__")
d_object, status = client.create_object("__DETECTION_LABEL_ID__", "__IMAGE_ID__", [xmin, ymin, xmax, ymax])
d_object, status = client.get_object(d_object.id)
# get all objects of image
d_objects, status = client.get_objects_of_image("__IMAGE_ID__")
```
Then you can create your task:
```python
detection_task.train()
```
Removing entities is same as in recognition client:
```python
client.remove_task("__DETECTION_TASK_ID__")
client.remove_label("__DETECTION_LABEL_ID__") # this will delete all objects which were created as this label
client.remove_object("__DETECTION_OBJECT_ID__")
client.remove_image("__IMAGE_ID__")
task.remove()
label.remove()
object1 = client.get_object("__DETECTION_OBJECT_ID__")
object1.remove()
image.remove()
```
Getting Detection Result:
```python
result = detection_task.detect([{"_url": "__URL_PATH_TO_IMAGE__"}])
```
Extracting object from image:
```python
image, status = client.get_image("59f7240d-ca86-436b-b0cd-30f4b94705df")
object1, status = client.get_object("__DETECTION_OBJECT_ID__")
extracted_image_record = image.extract_object_data(object1.data)
```
## Speeding it up with Parallel Processing
If you are uploading/classifying thousands of images and really need to speed it up, then you can use method parallel_records_processing:
```python
# classifying images in Ximilar Custom Recognition service
result = client.parallel_records_processing([{"_url": image} for image in images], method=task.classify, output=True, max_workers=3)
# detection images in Ximilar Custom Object Detection
result = client.parallel_records_processing([{"_url": image} for image in images], method=task.detect, output=True, max_workers=3)
# uploading images
result = client.parallel_records_processing([{"_url": image, "labels": ["__LABEL_ID_1__"]} for image in images], method=client.upload_images, output=True)
```
This method works only for getting result for classification, tagging, detection, color extraction or uploading images (All methods which use json records as input).
## Ximilar Visual Search
Service for visual fashion search. For more information see docs.ximilar.com
```python
from ximilar.client.visual import SimilarityFashionClient
client = SimilarityFashionClient(token='__API_TOKEN__', collection_id='__COLLECTION_ID__')
# inserting image requires _id and product_id
client.insert([{"_id": "__IMAGE_ID__", "product_id": "__PRODUCT_ID__", "_url": "__URL_PATH_TO_IMAGE__"}])
result = client.detect([{"_url": "__URL_PATH_TO_IMAGE__"}])
# search in collection
result = client.search([{"_url": "__URL_PATH_TO_IMAGE__"}])
```
## Ximilar Dominant Colors
You can select the service for extracting dominant colors by type of your image. If the image is from Product/Fashion domain, which means that product is tipically on some solid background then us `DominanColorProductClient`.
```python
from ximilar.client import DominantColorProductClient, DominantColorGenericClient
product_client = DominantColorProductClient(token="__API_TOKEN__")
generic_client = DominantColorGenericClient(token="__API_TOKEN__")
result = product_client.dominantcolor([{"_url": "__URL_PATH_TO_IMAGE__"}])
print(result['records'][0]['_dominant_colors'])
```
## Ximilar Generic and Fashion Tagging
Tagging contains two clients in similar way as DominanColors do.
```python
from ximilar.client import FashionTaggingClient, GenericTaggingClient
fashion_client = FashionTaggingClient(token="__API_TOKEN__")
generic_client = GenericTaggingClient(token="__API_TOKEN__")
result = generic_client.tags([{"_url": "__URL_PATH_TO_IMAGE__"}])
print(result['records'][0]['_tags'])
result = fashion_client.tags([{"_url": "__URL_PATH_TO_IMAGE__"}])
print(result['records'][0]['_tags'])
result = fashion_client.meta_tags([{"_url": "__URL_PATH_TO_IMAGE__"}])
print(result['records'][0]['_tags_meta_simple'])
```
## Ximilar Photo and Product similarity
These two services provides visual search (similarity search) for generic (stock) photos or products (e-commerce, fashion, ...).
When initializing client you need to specify both `token` and your `collection_id` that we created for you.
```python
from ximilar.client.search import SimilarityPhotosClient, SimilarityProductsClient
client = SimilarityPhotosClient(token='__API_TOKEN__', collection_id='__COLLECTION_ID__')
client = SimilarityProductsClient(token='__API_TOKEN__', collection_id='__COLLECTION_ID__')
# get random 7 items from database and return also _url if is present in item
result = client.random(count=7, fields_to_return=['_id', '_url'])
# search 10 most visually similar items for item in your index
result = client.search({'_id': '__ITEM_ID__'}, k=10)
# search 5 most visually similar items for external item (not in index) defined by _url field
result = client.search({'_url': '__URL_PATH_TO_IMAGE__'}, k=5)
# search visually similar items, return also _url field if present in item and
# search only for items defined by filter (mongodb syntax)
result = client.search({'_id': '__ITEM_ID__'}, fields_to_return=['_id', '_url'],
filter={
'meta-category-x': { '$in': ['__SOME_VALUE_1__', '__SOME_VALUE_2__']},
'some-field': '__SOME_VALUE__'
})
```
All crud operations:
```python
# get list of items from index
result = client.get_records([{'_id': '__ITEM_ID__'}, {'_id': '__ITEM_ID__'}])
# insert item tot he index with your _id, and onr of _url | _base64, and other fields (meta-info) which you can
# then use when applying filter in search or random menthods
result = client.insert([{'_id': '__ITEM_ID__', '_url': '__URL_PATH_TO_IMAGE__',
'meta-category-x': '__CATEGORY_OF_ITEM__',
'meta-info-y': '__ANOTHER_META_INFO__'}])
# delete item from id
result = client.remove([{'_id': '__ITEM_ID__'}])
# update item in index with all additional fields and meta-info
result = client.update([{'_id': '__ITEM_ID__', 'some-additional-field': '__VALUE__'}])
```
## Custom Similarity
This service let you train your custom image similarity model.
Creating entities is similar to recognition or detection service.
```python
from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
tasks, _ = client.get_all_tasks()
task, _ = client.create_task("__NAME__", "__DESCRIPTION__")
type1, _ = client.create_type("__NAME__", "__DESCRIPTION__")
group, _ = client.create_group("__NAME__", "__DESCRIPTION__", type1.id)
```
Add/Remove types to/from task:
```python
task.add_type(type1.id)
task.remove_type(type1.id)
```
Add/Remove images to/from group:
```python
group.add_images(["__IMAGE_ID_1__"])
group.remove_images(["__IMAGE_ID_1__"])
group.refresh()
```
Add/Remove groups to/from group:
```python
group.add_groups(["__GROUP_ID_1__"])
group.remove_groups(["__GROUP_ID_1__"])
group.refresh()
```
Set unset group as test (test flag is for evaluation dataset):
```python
group.set_test(True) # or False if unsetting from eval dataset
group.refresh()
```
Searching groups with name:
```python
client.get_all_groups_by_name("__NAME__")
```
# Tools
In our `tools` folder you can find some useful scripts for:
* `uploader.py` for uploading all images from specific folder
* `data_saver.py` for saving entire recognition and detection workspace including images
* `data_wiper.py` for removing entire workspace and all your data in workspace
* `detection_cutter.py` cutting objects from images
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/ximilar-public/ximilar-vize-api",
"name": "ximilar-client",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "machine learning, multimedia, json, rest, data",
"author": "Michal Lukac, David Novak and Ximilar.com Team",
"author_email": "tech@ximilar.com",
"download_url": "https://files.pythonhosted.org/packages/e8/6a/cfaed8ba09aac598ee64ca359ef37066d0919857700a877fd3d837db8e5e/ximilar-client-1.33.0.tar.gz",
"platform": null,
"description": "# Ximilar API Python Client\n\n\n\nThis Python 3.9+ Client library is lightweight wrapper for `ximilar.com`. \n\n## Installation\n\nPyPI - (https://pypi.org/project/ximilar-client/):\n\n # we recommend to install ximilar-client to new virtualenv\n pip install ximilar-client\n\nManual installation with latest changes:\n\n 1. Cloning the repo\n git clone https://gitlab.com/ximilar-public/ximilar-client.git\n 2. Install it with pip to your virtualenv\n pip install -e ximilar-client\n\n\nThis will install also urllib3, requests, tqdm and pytest library. This will not install python-opencv which is required if you want to upload local images to the Ximilar system. For more information about installing opencv on different systems we have a small page in our [docs](https://docs.ximilar.com/quickstart/client_opencv/).\n\n***You will need to install one of opencv-python or opencv-contrib-python (or headless) manually.***\n\n## Usage\n\nFirst you need to register via `app.ximilar.com` and obtain your `API TOKEN` for communication with ximilar rest endpoints. You can obtain the token from the [Ximilar App](https://app.ximilar.com/) at your profile page. \nAfter you obtain the token, the usage is quite straightforward. First, import this package and create specific rest client (reconition/vize, tagging, colors, search, ...). In following example we will create client for `Ximilar Recognition Service` (vize.ai). For all other Ximilar Services as Tagging, Custom Object Detection you will need to contact `tech@ximilar.com` first, so they will provide you access to the service: \n\n```python\nfrom ximilar.client import RecognitionClient, DetectionClient\nfrom ximilar.client import DominantColorProductClient, DominantColorGenericClient\nfrom ximilar.client import FashionTaggingClient, GenericTaggingClient\n\napp_client = RecognitionClient(token=\"__API_TOKEN__\")\ndetect_client = DetectionClient(token=\"__API_TOKEN__\")\n...\n```\n\n## Workspaces\n\nWith a new version of Ximilar App you are able to work also with workspaces. Workspaces are entities where all your task, labels and images live. Each user has by default workspace with name `Default` (it will be used if you do not specify workspace when working with Image, Label, Task). However you can specify id of workspace in the constructor.\n\n```python\nclient = RecognitionClient(token=\"__API_TOKEN__\", workspace='__UUID_OF_YOUR_WORKSPACE__')\nclient = DetectionClient(token=\"__API_TOKEN__\", workspace='__UUID_OF_YOUR_WORKSPACE__')\n```\n\n## Ximilar Recognition\nThis client allows you to work with Ximilar Recognition Service. With this client you are able to create classification or tagging tasks based on latest trends in machine learning and neural networks.\nAfter creating client object you can for example load your existing task and call train:\n\n```python\ntask, status = client.get_task(task_id='__ID_TASK_')\n\n# Every label in the task must have at least 20 images before training.\n# The training can take up to several hours as we are trying to achieve really high quality\n# solution. This endpoint will immediately return success if your task is in training queue.\ntask.train() \n\n# or you can list all your available tasks\ntasks, status = client.get_all_tasks()\n\n# or you can create new classification task\n# each Task, Image, Label is identified by unique ID\ntask, status = client.create_task('__TASK_NAME__')\n```\n\n#### Task\n\nCurrently there are two types of task to create. User can select 'multi_class' (default) or 'multi_label'. See ximilar.docs for more info.\n\n```python\n# categorization/classification or multi class task means that image is assigned to exactly one label\n# labels are exclusive which means image can contain only 'cat' or only 'dog'\nclassification_task, status = client.create_task('__TASK_NAME__')\n\n# tagging or multi label task means that image can have one or more labels\n# for example image can contain 'cat', 'dog' and 'animal' labels if there are on the picture\ntagging_task, status = client.create_task('__TASK_NAME__', type='multi_label')\n\n# removing task is possible through client object or task itself\nclient.remove_task(task.id)\ntask.remove()\n```\n\n#### Classify\n\nSuppose you want to use the task to predict the result on your images. Please, always try to send image bigger than 200px and lower than 600px for quality and speed:\n\n```python\n# you can send image in _file, _url or _base64 format\n# the _file format is intenally converted to _base64 as rgb image\nresult = task.classify([{'_url': '__URL_PATH_TO_IMG__'}, {'_file', '__LOCAL_FILE_PATH__'}, {'_base64': '__BASE64_DATA__'}])\n\n# the result is in json/dictionary format and you can access it in following way:\nbest_label = result['records'][0]['best_label']\n```\n\n#### Labels\n\nLabels are connected to the task. Depends which task you are working with (Tagging/multi_label or Categorization/multi_class) you can create Tag or Category labels. Working with the labels are pretty simple:\n\n```python\n# getting existing label\nexisting_label, status = client.get_label('__ID_LABEL__')\n\n# creating new label (CATEGORY, which is default) and attaching it to existing Categorization task (multi class)\nlabel, status = client.create_label(name='__NEW_LABEL_NAME__')\ntask.add_label(label.id)\n\n# creating new label (TAG) for Tagging task (multi label)\nlabel, status = client.create_label(name='__NEW_LABEL_NAME__', label_type='tag')\n\n# get all labels which are connected to the task\nlabels, status = task.get_labels()\n\nfor label in labels:\n print(label.id, label.name)\n\n# get label with exact name which is also connected to specific task\nlabel, status = task.get_label_by_name(name='__LABEL_NAME__')\n\n# detaching (not deleting) existing label from existing task\ntask.detach_label(label.id)\n\n# remove label (which also detach label from all tasks)\nclient.remove_label(label.id)\n\n# detach image from label\nlabel.detach_image(image.id)\n\n# search labels which contains given substring in name\nlabels, status = client.get_labels_by_substring('__LABEL_NAME__')\n```\n\n#### Working with training images\n\nImage is main entity in Ximilar system. Every image can have multiple labels (Recognition service) or multiple objects (Detection service).\n\n```python\n# getting all images of label (paginated result)\nimages, next_page, status = label.get_training_images()\nwhile images:\n for image in images:\n print(str(image.id))\n\n if not next_page:\n break\n images, next_page, status = label.get_training_images(next_page)\n\n# basic operations\nimage, status = client.get_image(image_id=image.id)\nimage.add_label(label.id)\n\n# detach label from image\nimage.detach_label(label.id)\n\n# deleting image \nclient.remove_image(image.id)\n```\n\nLet's say you want to upload a training image and add several labels to this image:\n\n```python\nimages, status = client.upload_images([{'_url': '__URL_PATH_TO_IMAGE__', 'labels': [label.id for label in labels], \"meta_data\": {\"field\": \"key\"}},\n {'_file': '__LOCAL_FILE_PATH__', 'labels': [label.id for label in labels]},\n {'_base64': '__BASE64_DATA__', 'labels': [label.id for label in labels]}])\n\n# and maybe add another label to the first image\nimages[0].add_label(\"__SOME_LABEL_ID__\")\n```\n\nUpload image without resizing it (for example Custom Object Detection requires high resolution images):\n\n```python\nimages, status = client.upload_images([{'_url': '__URL_PATH_TO_IMAGE__', \"noresize\": True}])\n```\n\nEvery image can have some meta data stored:\n\n```python\nimage.add_meta_data({\"__KEY_1__\": \"value\", \"__KEY_2__\": {\"THIS CAB BE\":\"COMPLEX\"}})\nimage.clear_meta_data()\n```\n\nEvery image can be marked with **test** flag (for evaluation on independent test dataset only):\n\n```python\nimage.set_test(True)\n```\n\nEvery image can be marked as real (default) or product. Product image should be images where is dominant one object on nice solid background. We can do more augmentations on these images.\n\n```python\nimage.set_real(False) # will mark image as product\n```\n\n## Ximilar Flows\n\nThe client is able to get flow of the json or process images/records by the flow.\n\n```python\nfrom ximilar.client import FlowsClient\n\nclient = FlowsClient(\"__API_TOKEN__\")\n\n# get flow\nflow, _ = client.get_flow(\"__FLOW_ID__\")\n\n# two way to call the flow on records\nclient.process_flow(flow.id, records)\nflow.proces(records)\n```\n\n\n## Ximilar Object Detection\n\nXimilar Object Detection is service which will help you find exact location (Bounding Box/Object with four coordinates xmin, ymin, xmax, ymax).\nIn similar way as Ximilar Recognition, here we also have Tasks, Labels and Images. However one more entity called Object is present in Ximilar Object Detection.\n\nFirst you need to create/get Detection Task:\n\n```python\nclient = DetectionClient(\"__API_TOKEN__\")\ndetection_task, status = client.create_task(\"__DETECTION_TASK_NAME__\")\ndetection_task, status = client.get_task(task.id)\n```\n\nSecond you need to create Detection Label and connect it to the task:\n\n```python\ndetection_label, status = client.create_label(\"__DETECTION_LABEL_NAME__\")\ndetection_label, status = client.get_label(\"__DETECTION_LABEL_ID__\")\n\ndetection_task.add_label(detection_label.id)\n```\n\nLastly you need to create Objects/Bounding box annotations of some type (Label) on the images:\n\n```python\nimage, status = client.get_image(\"__IMAGE_ID__\")\nd_object, status = client.create_object(\"__DETECTION_LABEL_ID__\", \"__IMAGE_ID__\", [xmin, ymin, xmax, ymax])\nd_object, status = client.get_object(d_object.id)\n\n# get all objects of image\nd_objects, status = client.get_objects_of_image(\"__IMAGE_ID__\")\n```\n\nThen you can create your task:\n\n```python\ndetection_task.train()\n```\n\nRemoving entities is same as in recognition client:\n\n```python\nclient.remove_task(\"__DETECTION_TASK_ID__\")\nclient.remove_label(\"__DETECTION_LABEL_ID__\") # this will delete all objects which were created as this label\nclient.remove_object(\"__DETECTION_OBJECT_ID__\")\nclient.remove_image(\"__IMAGE_ID__\")\n\ntask.remove()\nlabel.remove()\n\nobject1 = client.get_object(\"__DETECTION_OBJECT_ID__\")\nobject1.remove()\nimage.remove()\n```\n\nGetting Detection Result:\n\n```python\nresult = detection_task.detect([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\n```\n\nExtracting object from image:\n\n```python\nimage, status = client.get_image(\"59f7240d-ca86-436b-b0cd-30f4b94705df\")\n\nobject1, status = client.get_object(\"__DETECTION_OBJECT_ID__\")\nextracted_image_record = image.extract_object_data(object1.data)\n```\n\n## Speeding it up with Parallel Processing\n\nIf you are uploading/classifying thousands of images and really need to speed it up, then you can use method parallel_records_processing:\n\n```python\n# classifying images in Ximilar Custom Recognition service\nresult = client.parallel_records_processing([{\"_url\": image} for image in images], method=task.classify, output=True, max_workers=3)\n\n# detection images in Ximilar Custom Object Detection\nresult = client.parallel_records_processing([{\"_url\": image} for image in images], method=task.detect, output=True, max_workers=3)\n\n# uploading images\nresult = client.parallel_records_processing([{\"_url\": image, \"labels\": [\"__LABEL_ID_1__\"]} for image in images], method=client.upload_images, output=True)\n```\n\nThis method works only for getting result for classification, tagging, detection, color extraction or uploading images (All methods which use json records as input).\n\n## Ximilar Visual Search\n\nService for visual fashion search. For more information see docs.ximilar.com\n\n```python\nfrom ximilar.client.visual import SimilarityFashionClient\n\nclient = SimilarityFashionClient(token='__API_TOKEN__', collection_id='__COLLECTION_ID__')\n\n# inserting image requires _id and product_id\nclient.insert([{\"_id\": \"__IMAGE_ID__\", \"product_id\": \"__PRODUCT_ID__\", \"_url\": \"__URL_PATH_TO_IMAGE__\"}])\nresult = client.detect([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\n\n# search in collection\nresult = client.search([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\n```\n\n\n## Ximilar Dominant Colors\n\nYou can select the service for extracting dominant colors by type of your image. If the image is from Product/Fashion domain, which means that product is tipically on some solid background then us `DominanColorProductClient`.\n\n```python\nfrom ximilar.client import DominantColorProductClient, DominantColorGenericClient\n\nproduct_client = DominantColorProductClient(token=\"__API_TOKEN__\")\ngeneric_client = DominantColorGenericClient(token=\"__API_TOKEN__\")\n\nresult = product_client.dominantcolor([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\nprint(result['records'][0]['_dominant_colors'])\n```\n\n## Ximilar Generic and Fashion Tagging\n\nTagging contains two clients in similar way as DominanColors do.\n\n```python\nfrom ximilar.client import FashionTaggingClient, GenericTaggingClient\n\nfashion_client = FashionTaggingClient(token=\"__API_TOKEN__\")\ngeneric_client = GenericTaggingClient(token=\"__API_TOKEN__\")\n\nresult = generic_client.tags([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\nprint(result['records'][0]['_tags'])\n\nresult = fashion_client.tags([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\nprint(result['records'][0]['_tags'])\n\nresult = fashion_client.meta_tags([{\"_url\": \"__URL_PATH_TO_IMAGE__\"}])\nprint(result['records'][0]['_tags_meta_simple'])\n\n```\n\n## Ximilar Photo and Product similarity\n\nThese two services provides visual search (similarity search) for generic (stock) photos or products (e-commerce, fashion, ...).\nWhen initializing client you need to specify both `token` and your `collection_id` that we created for you.\n\n```python\nfrom ximilar.client.search import SimilarityPhotosClient, SimilarityProductsClient\n\nclient = SimilarityPhotosClient(token='__API_TOKEN__', collection_id='__COLLECTION_ID__')\nclient = SimilarityProductsClient(token='__API_TOKEN__', collection_id='__COLLECTION_ID__')\n\n# get random 7 items from database and return also _url if is present in item\nresult = client.random(count=7, fields_to_return=['_id', '_url'])\n\n# search 10 most visually similar items for item in your index\nresult = client.search({'_id': '__ITEM_ID__'}, k=10)\n\n# search 5 most visually similar items for external item (not in index) defined by _url field\nresult = client.search({'_url': '__URL_PATH_TO_IMAGE__'}, k=5)\n\n# search visually similar items, return also _url field if present in item and \n# search only for items defined by filter (mongodb syntax)\nresult = client.search({'_id': '__ITEM_ID__'}, fields_to_return=['_id', '_url'],\n filter={\n 'meta-category-x': { '$in': ['__SOME_VALUE_1__', '__SOME_VALUE_2__']},\n 'some-field': '__SOME_VALUE__'\n })\n```\n\nAll crud operations:\n\n```python\n# get list of items from index\nresult = client.get_records([{'_id': '__ITEM_ID__'}, {'_id': '__ITEM_ID__'}])\n\n# insert item tot he index with your _id, and onr of _url | _base64, and other fields (meta-info) which you can \n# then use when applying filter in search or random menthods\nresult = client.insert([{'_id': '__ITEM_ID__', '_url': '__URL_PATH_TO_IMAGE__',\n 'meta-category-x': '__CATEGORY_OF_ITEM__',\n 'meta-info-y': '__ANOTHER_META_INFO__'}])\n\n# delete item from id\nresult = client.remove([{'_id': '__ITEM_ID__'}])\n\n# update item in index with all additional fields and meta-info\nresult = client.update([{'_id': '__ITEM_ID__', 'some-additional-field': '__VALUE__'}])\n```\n\n## Custom Similarity\n\nThis service let you train your custom image similarity model.\n\nCreating entities is similar to recognition or detection service.\n\n```python\nfrom ximilar.client.similarity import CustomSimilarityClient\nclient = CustomSimilarityClient(\"__API__TOKEN__\")\ntasks, _ = client.get_all_tasks()\n\ntask, _ = client.create_task(\"__NAME__\", \"__DESCRIPTION__\")\ntype1, _ = client.create_type(\"__NAME__\", \"__DESCRIPTION__\")\ngroup, _ = client.create_group(\"__NAME__\", \"__DESCRIPTION__\", type1.id)\n```\n\nAdd/Remove types to/from task:\n\n```python\ntask.add_type(type1.id)\ntask.remove_type(type1.id)\n```\n\nAdd/Remove images to/from group:\n\n```python\ngroup.add_images([\"__IMAGE_ID_1__\"])\ngroup.remove_images([\"__IMAGE_ID_1__\"])\ngroup.refresh()\n```\n\nAdd/Remove groups to/from group:\n\n```python\ngroup.add_groups([\"__GROUP_ID_1__\"])\ngroup.remove_groups([\"__GROUP_ID_1__\"])\ngroup.refresh()\n```\n\nSet unset group as test (test flag is for evaluation dataset):\n\n```python\ngroup.set_test(True) # or False if unsetting from eval dataset\ngroup.refresh()\n```\n\nSearching groups with name:\n\n```python\nclient.get_all_groups_by_name(\"__NAME__\")\n```\n\n# Tools\n\nIn our `tools` folder you can find some useful scripts for:\n\n* `uploader.py` for uploading all images from specific folder\n* `data_saver.py` for saving entire recognition and detection workspace including images\n* `data_wiper.py` for removing entire workspace and all your data in workspace\n* `detection_cutter.py` cutting objects from images\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "The Ximilar App and Vize.ai Client.",
"version": "1.33.0",
"project_urls": {
"Homepage": "https://gitlab.com/ximilar-public/ximilar-vize-api"
},
"split_keywords": [
"machine learning",
" multimedia",
" json",
" rest",
" data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b79c6e77a8d27dd438b221b1e257d077c2e86a93b1236645a58bd10ab9cb60f",
"md5": "f2df0bce451698b0b67cf855ef02282e",
"sha256": "4690ed90a53bbac0fb5222dd810c3b25a0a75041c7e8d7eb86d21ff12dd4857a"
},
"downloads": -1,
"filename": "ximilar_client-1.33.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2df0bce451698b0b67cf855ef02282e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 55841,
"upload_time": "2024-11-20T10:48:16",
"upload_time_iso_8601": "2024-11-20T10:48:16.437279Z",
"url": "https://files.pythonhosted.org/packages/2b/79/c6e77a8d27dd438b221b1e257d077c2e86a93b1236645a58bd10ab9cb60f/ximilar_client-1.33.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e86acfaed8ba09aac598ee64ca359ef37066d0919857700a877fd3d837db8e5e",
"md5": "facd0753b44ffc89cf387858ea5750e1",
"sha256": "140f0df382e13e55dd1eb8d913215b29182d241b8c37eda2b50ff85a56a55cab"
},
"downloads": -1,
"filename": "ximilar-client-1.33.0.tar.gz",
"has_sig": false,
"md5_digest": "facd0753b44ffc89cf387858ea5750e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 50603,
"upload_time": "2024-11-20T10:48:17",
"upload_time_iso_8601": "2024-11-20T10:48:17.531054Z",
"url": "https://files.pythonhosted.org/packages/e8/6a/cfaed8ba09aac598ee64ca359ef37066d0919857700a877fd3d837db8e5e/ximilar-client-1.33.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 10:48:17",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ximilar-public",
"gitlab_project": "ximilar-vize-api",
"lcname": "ximilar-client"
}
JSON