Package: azure-cognitiveservices-vision-computervision
Azure Cognitive Services Computer Vision SDK for PythonThe Computer Vision service provides developers with access to advanced algorithms for processing images and returning information. Computer Vision algorithms analyze the content of an image in different ways, depending on the visual features you're interested in.You can use Computer Vision in your application to:Analyze images for insightExtract text from imagesGenerate thumbnailsLooking for more documentation?SDK reference documentationCognitive Services Computer Vision documentationPrerequisitesAzure subscription -Create a free accountAzureComputer Vision resourcePython 3.6+If you need a Computer Vision API account, you can create one with thisAzure CLIcommand:RES_REGION=westeuropeRES_GROUP=<resourcegroup-name>ACCT_NAME=<computervision-account-name>

azcognitiveservicesaccountcreate\--resource-group$RES_GROUP\--name$ACCT_NAME\--location$RES_REGION\--kindComputerVision\--skuS1\--yesInstallationInstall the Azure Cognitive Services Computer Vision SDK withpip, optionally within avirtual environment.Configure a virtual environment (optional)Although not required, you can keep your base system and Azure SDK environments isolated from one another if you use avirtual environment. Execute the following commands to configure and then enter a virtual environment withvenv, such ascogsrv-vision-env:python3-mvenvcogsrv-vision-envsourcecogsrv-vision-env/bin/activateInstall the SDKInstall the Azure Cognitive Services Computer Vision SDK for Pythonpackagewithpip:pipinstallazure-cognitiveservices-vision-computervisionAuthenticationOnce you create your Computer Vision resource, you need itsregion, and one of itsaccount keysto instantiate the client object.Use these values when you create the instance of theComputerVisionClientclient object.Get credentialsUse theAzure CLIsnippet below to populate two environment variables with the Computer Vision accountregionand one of itskeys(you can also find these values in theAzure portal). The snippet is formatted for the Bash shell.RES_GROUP=<resourcegroup-name>ACCT_NAME=<computervision-account-name>exportACCOUNT_REGION=$(azcognitiveservicesaccountshow\--resource-group$RES_GROUP\--name$ACCT_NAME\--querylocation\--outputtsv)exportACCOUNT_KEY=$(azcognitiveservicesaccountkeyslist\--resource-group$RES_GROUP\--name$ACCT_NAME\--querykey1\--outputtsv)Create clientOnce you've populated theACCOUNT_REGIONandACCOUNT_KEYenvironment variables, you can create theComputerVisionClientclient object.fromazure.cognitiveservices.vision.computervisionimportComputerVisionClientfromazure.cognitiveservices.vision.computervision.modelsimportVisualFeatureTypesfrommsrest.authenticationimportCognitiveServicesCredentialsimportosregion=os.environ['ACCOUNT_REGION']key=os.environ['ACCOUNT_KEY']credentials=CognitiveServicesCredentials(key)client=ComputerVisionClient(endpoint="https://"+region+".api.cognitive.microsoft.com/",credentials=credentials)UsageOnce you've initialized aComputerVisionClientclient object, you can:Analyze an image: You can analyze an image for certain features such as faces, colors, tags.Generate thumbnails: Create a custom JPEG image to use as a thumbnail of the original image.Get description of an image: Get a description of the image based on its subject domain.For more information about this service, seeWhat is Computer Vision?.ExamplesThe following sections provide several code snippets covering some of the most common Computer Vision tasks, including:Analyze an imageGet subject domain listAnalyze an image by domainGet text description of an imageGet handwritten text from imageGenerate thumbnailAnalyze an imageYou can analyze an image for certain features withanalyze_image. Use thevisual_featuresproperty to set the types of analysis to perform on the image. Common values areVisualFeatureTypes.tagsandVisualFeatureTypes.description.url="https://upload.wikimedia.org/wikipedia/commons/thumb/1/12/Broadway_and_Times_Square_by_night.jpg/450px-Broadway_and_Times_Square_by_night.jpg"image_analysis=client.analyze_image(url,visual_features=[VisualFeatureTypes.tags])fortaginimage_analysis.tags:print(tag)Get subject domain listReview the subject domains used to analyze your image withlist_models. These domain names are used whenanalyzing an image by domain. An example of a domain islandmarks.models=client.list_models()forxinmodels.models_property:print(x)Analyze an image by domainYou can analyze an image by subject domain withanalyze_image_by_domain. Get thelist of supported subject domainsin order to use the correct domain name.domain="landmarks"url="https://images.pexels.com/photos/338515/pexels-photo-338515.jpeg"language="en"analysis=client.analyze_image_by_domain(domain,url,language)forlandmarkinanalysis.result["landmarks"]:print(landmark["name"])print(landmark["confidence"])Get text description of an imageYou can get a language-based text description of an image withdescribe_image. Request several descriptions with themax_descriptionproperty if you are doing text analysis for keywords associated with the image. Examples of a text description for the following image includea train crossing a bridge over a body of water,a large bridge over a body of water, anda train crossing a bridge over a large body of water.domain="landmarks"url="http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"language="en"max_descriptions=3analysis=client.describe_image(url,max_descriptions,language)forcaptioninanalysis.captions:print(caption.text)print(caption.confidence)Get text from imageYou can get any handwritten or printed text from an image. This requires two calls to the SDK:readandget_read_result. The call to read is asynchronous. In the results of the get_read_result call, you need to check if the first call completed withOperationStatusCodesbefore extracting the text data. The results include the text as well as the bounding box coordinates for the text.# import modelsfromazure.cognitiveservices.vision.computervision.modelsimportOperationStatusCodesurl="https://github.com/Azure-Samples/cognitive-services-python-sdk-samples/raw/master/samples/vision/images/make_things_happen.jpg"raw=TruenumberOfCharsInOperationId=36# SDK callrawHttpResponse=client.read(url,language="en",raw=True)# Get ID from returned headersoperationLocation=rawHttpResponse.headers["Operation-Location"]idLocation=len(operationLocation)-numberOfCharsInOperationIdoperationId=operationLocation[idLocation:]# SDK callresult=client.get_read_result(operationId)# Get dataifresult.status==OperationStatusCodes.succeeded:forlineinresult.analyze_result.read_results[0].lines:print(line.text)print(line.bounding_box)Generate thumbnailYou can generate a thumbnail (JPG) of an image withgenerate_thumbnail. The thumbnail does not need to be in the same proportions as the original image.This example uses thePillowpackage to save the new thumbnail image locally.fromPILimportImageimportiowidth=50height=50url="http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"thumbnail=client.generate_thumbnail(width,height,url)forxinthumbnail:image=Image.open(io.BytesIO(x))image.save('thumbnail.jpg')TroubleshootingGeneralWhen you interact with theComputerVisionClientclient object using the Python SDK, theComputerVisionErrorResponseExceptionclass is used to return errors. Errors returned by the service correspond to the same HTTP status codes returned for REST API requests.For example, if you try to analyze an image with an invalid key, a401error is returned. In the following snippet, theerroris handled gracefully by catching the exception and displaying additional information about the error.domain="landmarks"url="http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"language="en"max_descriptions=3try:analysis=client.describe_image(url,max_descriptions,language)forcaptioninanalysis.captions:print(caption.text)print(caption.confidence)exceptHTTPFailurease:ife.status_code==401:print("Error unauthorized. Make sure your key and region are correct.")else:raiseHandle transient errors with retriesWhile working with theComputerVisionClientclient, you might encounter transient failures caused byrate limitsenforced by the service, or other transient problems like network outages. For information about handling these types of failures, seeRetry patternin the Cloud Design Patterns guide, and the relatedCircuit Breaker pattern.Next stepsMore sample codeSeveral Computer Vision Python SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Computer Vision:See sample repoAdditional documentationFor more extensive documentation on the Computer Vision service, see theAzure Computer Vision documentationon docs.microsoft.com.Release History0.9.0 (2021-05-31)Breaking changesOperation ComputerVisionClientOperationsMixin.read has a new signatureOperation ComputerVisionClientOperationsMixin.read_in_stream has a new signature0.8.0 (2021-03-22)FeaturesModel Line has a new parameter appearanceModel TagResult has a new parameter model_versionModel DomainModelResults has a new parameter model_versionModel AreaOfInterestResult has a new parameter model_versionModel DetectResult has a new parameter model_versionModel ImageAnalysis has a new parameter model_versionModel ImageDescription has a new parameter model_versionModel OcrResult has a new parameter model_versionModel ComputerVisionError has a new parameter innererrorBreaking changesOperation ComputerVisionClientOperationsMixin.analyze_image has a new signatureOperation ComputerVisionClientOperationsMixin.analyze_image_by_domain has a new signatureOperation ComputerVisionClientOperationsMixin.analyze_image_by_domain_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.analyze_image_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.describe_image has a new signatureOperation ComputerVisionClientOperationsMixin.describe_image_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.detect_objects has a new signatureOperation ComputerVisionClientOperationsMixin.detect_objects_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.generate_thumbnail has a new signatureOperation ComputerVisionClientOperationsMixin.generate_thumbnail_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.get_area_of_interest has a new signatureOperation ComputerVisionClientOperationsMixin.get_area_of_interest_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.read_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.recognize_printed_text has a new signatureOperation ComputerVisionClientOperationsMixin.recognize_printed_text_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.tag_image has a new signatureOperation ComputerVisionClientOperationsMixin.tag_image_in_stream has a new signatureOperation ComputerVisionClientOperationsMixin.read has a new signatureModel AnalyzeResults has a new required parameter model_versionModel ComputerVisionError no longer has parameter request_id0.7.0 (2020-10-08)FeaturesSupports 3.1 service version0.6.0 (2020-05-18)FeaturesModel Line has a new parameter languageAdded operation ComputerVisionClientOperationsMixin.readAdded operation ComputerVisionClientOperationsMixin.get_read_resultAdded operation ComputerVisionClientOperationsMixin.read_in_streamBreaking changesParameter words of model Line is now requiredParameter bounding_box of model Line is now requiredParameter text of model Line is now requiredParameter confidence of model Word is now requiredRemoved operation ComputerVisionClientOperationsMixin.get_text_operation_resultRemoved operation ComputerVisionClientOperationsMixin.get_read_operation_resultRemoved operation ComputerVisionClientOperationsMixin.recognize_text_in_streamRemoved operation ComputerVisionClientOperationsMixin.recognize_textRemoved operation ComputerVisionClientOperationsMixin.batch_read_fileRemoved operation ComputerVisionClientOperationsMixin.batch_read_file_in_streamModel ReadOperationResult has a new signature0.5.0 (2019-10-01)FeaturesModel AdultInfo has a new parameter is_gory_contentModel AdultInfo has a new parameter gore_scoreBreaking changesOperation ComputerVisionClientOperationsMixin.analyze_image has a
new signatureOperation
ComputerVisionClientOperationsMixin.analyze_image_in_stream has a
new signatureOperation ComputerVisionClientOperationsMixin.describe_image has a
new signatureOperation
ComputerVisionClientOperationsMixin.describe_image_in_stream has
a new signature0.4.0 (2019-06-27)Breaking changes"batch_read_file" and "batch_read_file_in_stream" have no
"mode" parameter anymoreBugfix"bounding_box" now supports float numbersIncorrect "Not Started" typo for state reporting0.3.0 (2019-03-11)FeaturesModel ImageAnalysis has a new parameter brandsModel ImageAnalysis has a new parameter objectsModel Word has a new parameter confidenceBreaking changesClient ComputerVisionAPI has been renamed ComputerVisionClientParameter text of model Word is now requiredParameter bounding_box of model Word is now required0.2.0 (2018-06-22)Featuresanalyze_image now support 'en', 'es', 'ja', 'pt', 'zh' (including
"in_stream" version of these operations)describe_image/tag_image/analyze_image_by_domain now support
the language parameter (including "in_stream" version of these
operations)Client class can be used as a context manager to keep the underlying
HTTP session open for performanceBug fixesFix several invalid JSON description, that was raising unexpected
exceptions (including OCRResult from bug #2614)Breaking changesrecognize_text "detect_handwriting" boolean is now a "mode" str
between 'Handwritten' and 'Printed'General Breaking changesThis version uses a next-generation code generator thatmightintroduce breaking changes.Model signatures now use only keyword-argument syntax. All
positional arguments must be re-written as keyword-arguments. To
keep auto-completion in most cases, models are now generated for
Python 2 and Python 3. Python 3 uses the "*" syntax for
keyword-only arguments.Enum types now use the "str" mixin (class AzureEnum(str, Enum)) to
improve the behavior when unrecognized enum values are encountered.
While this is not a breaking change, the distinctions are important,
and are documented here:https://docs.python.org/3/library/enum.html#othersAt a glance:"is" should not be used at all."format" will return the string value, where "%s" string
formatting will returnNameOfEnum.stringvalue. Format syntax
should be prefered.New Long Running Operation:Return type changes frommsrestazure.azure_operation.AzureOperationPollertomsrest.polling.LROPoller. External API is the same.Return type is nowalwaysamsrest.polling.LROPoller,
regardless of the optional parameters used.The behavior has changed when usingraw=True. Instead of
returning the initial call result asClientRawResponse,
without polling, now this returns an LROPoller. After polling,
the final resource will be returned as aClientRawResponse.Newpollingparameter. The default behavior isPolling=Truewhich will poll using ARM algorithm. WhenPolling=False, the response of the initial call will be
returned without polling.pollingparameter accepts instances of subclasses ofmsrest.polling.PollingMethod.add_done_callbackwill no longer raise if called after
polling is finished, but will instead execute the callback right
away.0.1.0 (2018-01-23)Initial Release