CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-azure-cognitiveservices-vision-customvision

Microsoft Azure Custom Vision Client Library for Python providing training and prediction clients for custom computer vision models.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

prediction.mddocs/

Prediction Operations

Inference operations for trained Azure Custom Vision models. The prediction client provides functionality for making predictions on images using published custom vision models, supporting both image classification and object detection scenarios.

Capabilities

Client Initialization

Create and configure the prediction client with authentication credentials.

class CustomVisionPredictionClient:
    def __init__(self, endpoint: str, credentials):
        """
        Initialize the Custom Vision Prediction Client.

        Parameters:
        - endpoint: str, Custom Vision prediction endpoint URL
        - credentials: Authentication credentials object
        """

class CustomVisionPredictionClientConfiguration:
    """Prediction client configuration settings."""

Image Classification

Classify images using trained classification models with options for storing prediction results.

def classify_image(project_id: str, published_name: str, image_data: bytes, application: str = None) -> ImagePrediction:
    """
    Classify image and store prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_data: bytes, image binary data to classify
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Classification results with tag predictions and confidence scores
    """

def classify_image_with_no_store(project_id: str, published_name: str, image_data: bytes, 
                                application: str = None) -> ImagePrediction:
    """
    Classify image without storing prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_data: bytes, image binary data to classify
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Classification results without storage
    """

def classify_image_url(project_id: str, published_name: str, image_url: ImageUrl, 
                      application: str = None) -> ImagePrediction:
    """
    Classify image from URL and store prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_url: ImageUrl, wrapper object containing image URL
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Classification results with storage
    """

def classify_image_url_with_no_store(project_id: str, published_name: str, image_url: ImageUrl,
                                    application: str = None) -> ImagePrediction:
    """
    Classify image from URL without storing prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_url: ImageUrl, wrapper object containing image URL
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Classification results without storage
    """

Object Detection

Detect objects in images using trained object detection models with bounding box predictions.

def detect_image(project_id: str, published_name: str, image_data: bytes, application: str = None) -> ImagePrediction:
    """
    Detect objects in image and store prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_data: bytes, image binary data for object detection
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Object detection results with bounding boxes and confidence scores
    """

def detect_image_with_no_store(project_id: str, published_name: str, image_data: bytes,
                              application: str = None) -> ImagePrediction:
    """
    Detect objects in image without storing prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_data: bytes, image binary data for object detection
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Object detection results without storage
    """

def detect_image_url(project_id: str, published_name: str, image_url: ImageUrl,
                    application: str = None) -> ImagePrediction:
    """
    Detect objects in image from URL and store prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_url: ImageUrl, wrapper object containing image URL
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Object detection results with storage
    """

def detect_image_url_with_no_store(project_id: str, published_name: str, image_url: ImageUrl,
                                  application: str = None) -> ImagePrediction:
    """
    Detect objects in image from URL without storing prediction results.

    Parameters:
    - project_id: str, project identifier containing the model
    - published_name: str, name of published model iteration
    - image_url: ImageUrl, wrapper object containing image URL
    - application: str, optional application identifier for tracking

    Returns:
    ImagePrediction: Object detection results without storage
    """

Usage Examples

Classification Example

from azure.cognitiveservices.vision.customvision.prediction import CustomVisionPredictionClient
from azure.cognitiveservices.vision.customvision.prediction.models import ImageUrl
from msrest.authentication import ApiKeyCredentials

# Initialize client
prediction_key = "your-prediction-key"
endpoint = "https://southcentralus.api.cognitive.microsoft.com"
credentials = ApiKeyCredentials(in_headers={"Prediction-key": prediction_key})
client = CustomVisionPredictionClient(endpoint, credentials)

# Classify image from file
with open("image.jpg", "rb") as image_data:
    results = client.classify_image(
        project_id="your-project-id",
        published_name="your-model-name", 
        image_data=image_data.read()
    )

# Process results
for prediction in results.predictions:
    if prediction.probability > 0.5:
        print(f"Tag: {prediction.tag_name}, Confidence: {prediction.probability:.2%}")

# Classify image from URL
image_url = ImageUrl(url="https://example.com/image.jpg")
results = client.classify_image_url(
    project_id="your-project-id",
    published_name="your-model-name",
    image_url=image_url
)

Object Detection Example

# Detect objects in image
with open("image.jpg", "rb") as image_data:
    results = client.detect_image(
        project_id="your-project-id",
        published_name="your-detector-name",
        image_data=image_data.read()
    )

# Process detection results
for prediction in results.predictions:
    if prediction.probability > 0.3:
        bbox = prediction.bounding_box
        print(f"Object: {prediction.tag_name}")
        print(f"Confidence: {prediction.probability:.2%}")
        print(f"Bounding Box: ({bbox.left:.3f}, {bbox.top:.3f}, {bbox.width:.3f}, {bbox.height:.3f})")

Prediction Data Types

class ImagePrediction:
    """Main prediction result containing predictions and metadata."""
    id: str
    project: str
    iteration: str
    created: datetime
    predictions: list  # list[Prediction]

class Prediction:
    """Individual prediction with tag, probability, and optional bounding box."""
    probability: float
    tag_id: str
    tag_name: str
    bounding_box: BoundingBox = None  # Only for object detection

class BoundingBox:
    """Image region coordinates for object detection (normalized 0-1 values)."""
    left: float    # Left edge as fraction of image width
    top: float     # Top edge as fraction of image height  
    width: float   # Width as fraction of image width
    height: float  # Height as fraction of image height

class ImageUrl:
    """URL wrapper for image predictions."""
    url: str

class CustomVisionErrorException(Exception):
    """Exception raised for prediction API operation failures."""
    error: CustomVisionError

class CustomVisionError:
    """Detailed error information for prediction failures."""
    code: str
    message: str

Error Handling

from azure.cognitiveservices.vision.customvision.prediction.models import CustomVisionErrorException

try:
    results = client.classify_image(project_id, published_name, image_data)
except CustomVisionErrorException as e:
    print(f"Prediction failed: {e.error.code} - {e.error.message}")
    # Common error codes:
    # - BadRequest: Invalid image format or size
    # - NotFound: Project or published model not found  
    # - Unauthorized: Invalid prediction key
    # - QuotaExceeded: Prediction quota exceeded

Best Practices

Performance Optimization

  • Use *_with_no_store methods for high-volume inference to avoid storage costs
  • Batch predictions when possible to reduce API calls
  • Consider image size optimization (max 4MB, recommended under 1MB)

Confidence Thresholds

  • Classification: Typically filter results above 0.5-0.7 confidence
  • Object Detection: Use lower thresholds (0.3-0.5) to avoid missing objects
  • Adjust thresholds based on your specific use case and model performance

URL vs Binary Data

  • Use URL methods for images already hosted online
  • Use binary data methods for local files or when you need full control over image data
  • URLs must be publicly accessible (no authentication required)

Install with Tessl CLI

npx tessl i tessl/pypi-azure-cognitiveservices-vision-customvision

docs

index.md

prediction.md

training.md

tile.json