2023-10-13 14:57:41 -05:00
# Lookout for Vision code examples for the SDK for Python
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
## Overview
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
Shows how to use the AWS SDK for Python (Boto3) to work with Amazon Lookout for Vision.
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
<!--custom.overview.start-->
<!--custom.overview.end-->
2021-10-28 15:43:09 -07:00
2024-01-05 10:05:03 -05:00
_ Lookout for Vision enables you to find visual defects in industrial products, accurately and at scale. _
2023-10-13 14:57:41 -05:00
## ⚠ Important
2024-01-05 10:05:03 -05:00
* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing ](https://aws.amazon.com/pricing/ ) and [Free Tier ](https://aws.amazon.com/free/ ).
2023-10-13 14:57:41 -05:00
* Running the tests might result in charges to your AWS account.
* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege ](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege ).
* This code is not tested in every AWS Region. For more information, see [AWS Regional Services ](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services ).
<!--custom.important.start-->
<!--custom.important.end-->
2021-10-28 15:43:09 -07:00
## Code examples
2023-10-13 14:57:41 -05:00
### Prerequisites
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
For prerequisites, see the [README ](../../README.md#Prerequisites ) in the `python` folder.
Install the packages required by these examples by running the following in a virtual environment:
```
python -m pip install -r requirements.txt
```
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
<!--custom.prerequisites.start-->
<!--custom.prerequisites.end-->
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
### Get started
2024-01-05 10:05:03 -05:00
- [Hello Lookout for Vision ](hello.py#L4 ) (`ListProjects` )
2023-10-13 14:57:41 -05:00
### Single actions
Code excerpts that show you how to call individual service functions.
2024-04-30 12:22:08 -07:00
- [CreateDataset ](datasets.py#L32 )
- [CreateModel ](models.py#L29 )
- [CreateProject ](projects.py#L31 )
- [DeleteDataset ](datasets.py#L201 )
- [DeleteModel ](models.py#L167 )
- [DeleteProject ](projects.py#L54 )
- [DescribeDataset ](datasets.py#L227 )
- [DescribeModel ](models.py#L102 )
- [DetectAnomalies ](inference.py#L23 )
- [ListModels ](models.py#L143 )
- [ListProjects ](projects.py#L73 )
- [StartModel ](hosting.py#L30 )
- [StopModel ](hosting.py#L87 )
2023-10-13 14:57:41 -05:00
### Scenarios
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
Code examples that show you how to accomplish a specific task by calling multiple
functions within the same service.
2021-10-28 15:43:09 -07:00
2024-01-05 10:05:03 -05:00
- [Create a manifest file ](datasets.py )
2024-08-27 14:32:38 -04:00
- [Create, train, and start a model ](../../example_code/lookoutvision )
2024-01-05 10:05:03 -05:00
- [Export the datasets from a project ](export_datasets.py )
- [Find a project with a specific tag ](find_tag.py )
- [List models that are currently hosted ](hosting.py )
<!--custom.examples.start-->
<!--custom.examples.end-->
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
## Run the examples
### Instructions
<!--custom.instructions.start-->
2021-04-15 11:45:07 -07:00
There are three demonstrations in this set of examples:
2021-05-04 13:49:38 -07:00
* Create and host a model.
* Detect anomalies in images using a model.
2021-04-15 11:45:07 -07:00
* Find tags attached to a model.
Before running these demonstrations do the following:
- Follow the [setup instructions ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/su-set-up.html ).
2021-05-04 13:49:38 -07:00
- Read [Getting started with the SDK ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/getting-started-sdk.html ).
2023-10-13 14:57:41 -05:00
- Create an Amazon S3 bucket in your AWS account. You'll use the bucket to store your
training images, manifest files, and training output.
- Copy your training and test images to your S3 bucket. To try this code with example
images, You can use the example [circuit board dataset ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/su-prepare-example-images.html ).
2021-04-15 11:45:07 -07:00
The folder structures for the training and test images must be as follows:
```
2024-09-24 17:37:11 -04:00
s3://amzn-s3-demo-bucket/<train or test>/
2021-05-04 13:49:38 -07:00
normal/
anomaly/
2021-04-15 11:45:07 -07:00
```
`train` and `test` can be any folder path.
Place normal images in the `normal` folder. Anomalous images in the `anomaly` folder.
2023-10-13 14:57:41 -05:00
##### Example structure
2021-04-15 11:45:07 -07:00
The example contains the following files.
2023-10-13 14:57:41 -05:00
###### datasets.py
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
A class that shows how to create and manage datasets. Also shows how to create a
2021-10-28 15:43:09 -07:00
manifest file based on images found in an Amazon S3 bucket. Used by `train_host.py` .
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
Manifest files are used to create training and test datasets. `train_host.py` uses
`datasets.py` to create training and (optionally) test manifest files, and upload them
to an Amazon S3 bucket location that you specify. For more information about manifest
files, see [Creating a dataset using an Amazon SageMaker Ground Truth manifest file ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/create-dataset-ground-truth.html ).
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
###### find_tag.py
2021-04-15 11:45:07 -07:00
2021-10-28 15:43:09 -07:00
Shows how to find a tag attached to a Lookout for Vision model.
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
###### hello.py
2023-02-09 14:29:25 -08:00
Confirms that you can call Amazon Lookout for Vision operations.
If you haven't previously created a project in the current AWS Region,
the response is an empty list, however it confirms that you can call the
2023-10-13 14:57:41 -05:00
Lookout for Vision API.
2023-02-09 14:29:25 -08:00
2023-10-13 14:57:41 -05:00
###### hosting.py
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
A class that shows how to start and stop a Lookout for Vision project. Also shows how
2021-10-28 15:43:09 -07:00
to list hosted models. Used by `train_host.py` .
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
###### inference.py
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
A class that shows how to analyze an image (JPEG/PNG) with a hosted Lookout for Vision
2021-10-28 15:43:09 -07:00
model. You can also analyze an image stored in an Amazon S3 bucket.
2023-10-13 14:57:41 -05:00
The example shows how you can classify images as normal or anomalous. It also shows how to
2022-08-09 13:53:15 -07:00
use segmentation information returned from a segmentation model. For more information,
2023-10-13 14:57:41 -05:00
see [Detecting anomalies in an image ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/inference-detect-anomalies.html ).
To run the example, supply an image file name and a configuration JSON file with the following format.
2022-08-09 13:53:15 -07:00
{
2022-08-23 16:03:00 -07:00
"project" : "The Lookout for Vision project name.",
2022-08-09 13:53:15 -07:00
"model_version" : "The model version.",
"confidence_limit" : The minimum acceptable confidence. (Float 0 - 1).,
2022-08-23 16:03:00 -07:00
"coverage_limit" : The maximum acceptable percentage coverage of an anomaly (Float 0 - 1).,
2022-08-09 13:53:15 -07:00
"anomaly_types_limit" : The maximum number of allowable anomaly types. (Integer),
"anomaly_label" : "The anomaly label for the type of anomaly that you want to check."
}
We provide a template JSON configuration file in config.json.
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
###### models.py
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
A class that shows how to train and manage a Lookout for Vision model. Used by
2021-10-28 15:43:09 -07:00
`train_host.py` .
2023-10-13 14:57:41 -05:00
###### projects.py
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
A class that shows how to create and manage a Lookout for Vision project. Used by
2021-10-28 15:43:09 -07:00
`train_host.py` .
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
###### train_host.py
2021-10-28 15:43:09 -07:00
2023-10-13 14:57:41 -05:00
Shows how to create and host a model. The code creates a project, creates a manifest
file, creates a dataset using the manifest file, and trains a model. Finally, if
2021-10-28 15:43:09 -07:00
desired, the example shows how to host the model. Used by `train_host.py` .
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
###### find_running_models.py
You are charged for the amount of time that an Amazon Lookout for Vision model is
running (hosted). Use this script to find the running models in the commercial AWS
partition. You can stop a model by calling the [StopModel ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/run-stop-model.html ) operation.
2022-04-06 12:19:34 -07:00
2023-10-13 14:57:41 -05:00
###### update_dataset.py
2022-05-19 07:09:24 -07:00
Shows how to add or update images in an Amazon Lookout for Vision dataset.
2023-10-13 14:57:41 -05:00
###### export_datasets.py
2022-12-14 10:00:51 -08:00
Shows how to export the datasets from an Amazon Lookout for Vision project to an
Amazon S3 location.
Run this example at a command prompt with the following command.
```
python export_datasets.py <project> <destination>
```
- `project` - The project that you want to export the datasets from.
- `destination` - The Amazon S3 path that you want to copy the datasets to.
2023-10-13 14:57:41 -05:00
<!--custom.instructions.end-->
#### Hello Lookout for Vision
This example shows you how to get started using Lookout for Vision.
```
2024-07-03 17:16:21 -04:00
python hello.py
2023-10-13 14:57:41 -05:00
```
#### Create a manifest file
This example shows you how to create a Lookout for Vision manifest file and upload it to Amazon S3.
<!--custom.scenario_prereqs.lookoutvision_Scenario_CreateManifestFile.start-->
<!--custom.scenario_prereqs.lookoutvision_Scenario_CreateManifestFile.end-->
Start the example by running the following at a command prompt:
```
python datasets.py
```
<!--custom.scenarios.lookoutvision_Scenario_CreateManifestFile.start-->
<!--custom.scenarios.lookoutvision_Scenario_CreateManifestFile.end-->
2022-05-19 07:09:24 -07:00
2023-10-13 14:57:41 -05:00
#### Create, train, and start a model
2021-04-15 11:45:07 -07:00
2023-10-13 14:57:41 -05:00
This example shows you how to create, train, and start a Lookout for Vision model.
<!--custom.scenario_prereqs.lookoutvision_Scenario_CreateTrainStartModel.start-->
Start the example by running the following at a command prompt:
2024-01-05 10:05:03 -05:00
<!--custom.scenario_prereqs.lookoutvision_Scenario_CreateTrainStartModel.end-->
2023-10-13 14:57:41 -05:00
<!--custom.scenarios.lookoutvision_Scenario_CreateTrainStartModel.start-->
- `project` - A name for your project.
- `bucket` - The name of the Amazon S3 bucket in which to store your manifest files and
training output. The bucket must be in your AWS account and in the same AWS Region as
2024-09-24 17:37:11 -04:00
the Amazon S3 path supplied for `train` and `test`. For example, `amzn-s3-demo-bucket`.
2023-10-13 14:57:41 -05:00
- `train` - The Amazon S3 path where your training images are stored. For example,
2024-09-24 17:37:11 -04:00
`s3://amzn-s3-demo-bucket/circuitboard/train/`.
2023-10-13 14:57:41 -05:00
- `test` - (Optional) the Amazon S3 path where your test images are stored. For example,
2024-09-24 17:37:11 -04:00
`s3://amzn-s3-demo-bucket/circuitboard/test/`. If you don't supply a value,
2023-10-13 14:57:41 -05:00
Lookout for Vision splits the training dataset to create a test dataset.
After training completes, use the performance metrics to decide if the model's
performance is acceptable. For more information, see
[Improving your model](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/improve.html).
If you are satisfied with the model's performance, the code allows you to start the
model. After the model starts, use `inference.py` to analyze an image.
**You are charged for the amount of time that your model is running and for the time
taken to successfully train your model.**
<!--custom.scenarios.lookoutvision_Scenario_CreateTrainStartModel.end-->
#### Export the datasets from a project
This example shows you how to export the datasets from a Lookout for Vision project.
<!--custom.scenario_prereqs.lookoutvision_Scenario_ExportDatasets.start-->
<!--custom.scenario_prereqs.lookoutvision_Scenario_ExportDatasets.end-->
Start the example by running the following at a command prompt:
```
python export_datasets.py
```
<!--custom.scenarios.lookoutvision_Scenario_ExportDatasets.start-->
<!--custom.scenarios.lookoutvision_Scenario_ExportDatasets.end-->
#### Find a project with a specific tag
This example shows you how to find a Lookout for Vision project with a specific tag.
<!--custom.scenario_prereqs.lookoutvision_Scenario_FindTagInProjects.start-->
<!--custom.scenario_prereqs.lookoutvision_Scenario_FindTagInProjects.end-->
Start the example by running the following at a command prompt:
```
2024-01-05 10:05:03 -05:00
python find_tag.py
2023-10-13 14:57:41 -05:00
```
<!--custom.scenarios.lookoutvision_Scenario_FindTagInProjects.start-->
- tag - The key of the tag that you want to find.
- value - The value of the tag that you want to find.
For more information about tags, see [Tagging models](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/tagging-model.html).
<!--custom.scenarios.lookoutvision_Scenario_FindTagInProjects.end-->
#### List models that are currently hosted
This example shows you how to list Lookout for Vision models that are currently hosted.
<!--custom.scenario_prereqs.lookoutvision_Scenario_ListHostedModels.start-->
<!--custom.scenario_prereqs.lookoutvision_Scenario_ListHostedModels.end-->
Start the example by running the following at a command prompt:
```
python hosting.py
```
<!--custom.scenarios.lookoutvision_Scenario_ListHostedModels.start-->
<!--custom.scenarios.lookoutvision_Scenario_ListHostedModels.end-->
### Tests
⚠ Running tests might result in charges to your AWS account.
To find instructions for running these tests, see the [README](../../README.md#Tests)
in the ` python` folder.
<!--custom.tests.start-->
<!--custom.tests.end-->
## Additional resources
2024-01-05 10:05:03 -05:00
- [Lookout for Vision Developer Guide ](https://docs.aws.amazon.com/lookout-for-vision/latest/developer-guide/what-is.html )
- [Lookout for Vision API Reference ](https://docs.aws.amazon.com/lookout-for-vision/latest/APIReference/Welcome.html )
- [SDK for Python Lookout for Vision reference ](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lookoutvision.html )
2023-10-13 14:57:41 -05:00
<!--custom.resources.start-->
<!--custom.resources.end-->
2021-04-15 11:45:07 -07:00
---
2023-10-13 14:57:41 -05:00
2021-04-15 11:45:07 -07:00
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2023-10-13 14:57:41 -05:00
SPDX-License-Identifier: Apache-2.0
