aeyvision 0.1.0

Python SDK for Aey Vision API

AEY Vision Python SDK

Official Python SDK for the AEY Vision API - AI-powered video analytics for security and surveillance.

Installation

pip install aeyvision

Or install from source:

git clone https://github.com/yourusername/monorepo.git
cd monorepo/sdks/python
pip install -e .

Quick Start

from aeyvision import AeyVision, RegionCounterConfig

# Initialize the SDK
sdk = AeyVision(api_key='your-api-key')

# Configure analysis
config = [
    RegionCounterConfig(
        confidence=0.5,
        classes=['person', 'car'],
        zones=[{
            'name': 'entrance',
            'points': [[0, 0], [100, 0], [100, 100], [0, 100]]
        }]
    )
]

# Analyze video
result = sdk.analyze('path/to/video.mp4', config)
print(result)

Features

• Movement in Zone Detection: Track objects entering/exiting defined zones
• PPE Detection: Verify personal protective equipment compliance
• Video Redaction: Automatically blur faces, persons, or license plates
• ALPR: Automatic license plate recognition
• Age & Emotion Detection: Analyze demographics and emotional states
• Time in Region: Track how long objects spend in specific areas
• Entry/Exit Counting: Count objects crossing defined lines
• Fall Detection: Detect falls for safety monitoring

Configuration Options

RegionCounterConfig

Track and count objects in defined zones.

from aeyvision import RegionCounterConfig

config = RegionCounterConfig(
    type="region_counter",
    model="yolo11n.pt",
    classes=["person", "car", "truck"],
    confidence=0.5,
    zones=[
        {
            'name': 'zone1',
            'points': [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]
        }
    ]
)

PPEConfig

Detect personal protective equipment.

from aeyvision import PPEConfig

config = PPEConfig(
    type="ppe",
    confidence=0.5,
    required_ppe=["helmet", "vest", "gloves"]
)

RedactionConfig

Redact sensitive information from videos.

from aeyvision import RedactionConfig

config = RedactionConfig(
    type="redaction",
    backend="opencv",
    blur_kernel_size=[99, 99]
)

Advanced Usage

Get Annotated Video

# Return annotated video as bytes
annotated_video = sdk.analyze(
    'path/to/video.mp4',
    config,
    return_annotated=True
)

# Save to file
with open('output.mp4', 'wb') as f:
    f.write(annotated_video)

Multi-Feature Analysis

Run multiple analyzers on a single video for comprehensive insights. Save 25% on token costs when using 2 or more features together!

Using the Dedicated Method

# Run multiple analyzers on the same video
result = sdk.multi_feature_analysis(
    'video.mp4',
    features=[
        RegionCounterConfig(
            classes=['person'],
            zones=[{'name': 'entrance', 'points': [[0,0], [100,0], [100,100], [0,100]]}]
        ),
        PPEConfig(
            required_ppe=['hardhat', 'safety_vest']
        ),
        {
            'type': 'fall_detection',
            'confidence': 0.6
        }
    ]
)

# Access results for each analyzer
print(result['analyzers']['RegionCounterAnalyzer'])
print(result['analyzers']['PPEAnalyzer'])
print(result['analyzers']['FallDetectionAnalyzer'])

Using the Generic Method

# Run multiple analyzers on the same video
config = [
    RegionCounterConfig(
        classes=['person'],
        zones=[{'name': 'entrance', 'points': [[0,0], [100,0], [100,100], [0,100]]}]
    ),
    PPEConfig(
        required_ppe=['helmet', 'vest']
    )
]

result = sdk.analyze('video.mp4', config)

Real-World Use Cases

Construction Site Safety

# Monitor PPE compliance, track movement, and detect falls
result = sdk.multi_feature_analysis(
    'construction-site.mp4',
    features=[
        PPEConfig(required_ppe=['hardhat', 'safety_vest']),
        RegionCounterConfig(
            zones=[{'name': 'restricted_area', 'points': [[0.2,0.2], [0.8,0.2], [0.8,0.8], [0.2,0.8]]}]
        ),
        {'type': 'fall_detection'}
    ]
)

Parking Lot Security

# Track vehicles, read license plates, and monitor entry/exit
result = sdk.multi_feature_analysis(
    'parking-lot.mp4',
    features=[
        {'type': 'alpr'},
        {'type': 'entry_exit', 'lines': [{'name': 'gate', 'points': [[0.5,0], [0.5,1]]}]},
        RegionCounterConfig(
            zones=[{'name': 'parking_zone', 'points': [[0,0], [1,0], [1,1], [0,1]]}],
            classes=['car', 'truck']
        )
    ]
)

Retail Analytics

# Analyze customer demographics and track time in regions
result = sdk.multi_feature_analysis(
    'retail-store.mp4',
    features=[
        {'type': 'age_emotion'},
        {'type': 'time_in_region', 'zones': [{'name': 'product_display', 'points': [[0.3,0.3], [0.7,0.3], [0.7,0.7], [0.3,0.7]]}]}
    ]
)

Response Structure

{
  "meta": {
    "total_frames": 309,
    "fps": 29.97,
    "duration": 10.31,
    "processing_time": 3.58
  },
  "analyzers": {
    "RegionCounterAnalyzer": {
      "region_counts": {"entrance": 5},
      "total_tracks": 5
    },
    "PPEAnalyzer": {
      "violations": [],
      "compliance_rate": 1.0
    },
    "FallDetectionAnalyzer": {
      "falls_detected": 0
    }
  },
  "timing": {
    "processing_time": 3.67,
    "gpu_seconds": 3.67
  },
  "billing": {
    "tokens_used": 225,
    "gpu_seconds": 3.67,
    "tokens_per_gpu_second": 10
  }
}

Note: The tokens_used reflects the 25% discount (300 → 225 tokens) when using multiple features.

Custom Base URL

# Use a custom API endpoint
sdk = AeyVision(
    api_key='your-api-key',
    base_url='https://custom.api.endpoint.com'
)

API Response

The SDK returns a JSON response with the following structure:

{
  "meta": {
    "total_frames": 309,
    "fps": 29.97,
    "duration": 10.31,
    "processing_time": 3.58
  },
  "analyzers": {
    "RegionCounterAnalyzer": {
      "region_counts": {
        "entrance": 5
      },
      "total_tracks": 5,
      "detected_classes": ["person", "car"]
    }
  },
  "timing": {
    "processing_time": 3.67,
    "gpu_seconds": 3.67
  },
  "billing": {
    "tokens_used": 1,
    "gpu_seconds": 3.67,
    "tokens_per_gpu_second": 10
  }
}

Error Handling

try:
    result = sdk.analyze('video.mp4', config)
except Exception as e:
    print(f"Analysis failed: {e}")

Requirements

• Python 3.7+
• requests

License

MIT License - see LICENSE file for details

Support

• Documentation: https://docs.aeyvision.com
• Email: [e-mail]
• Issues: https://github.com/yourusername/monorepo/issues

python-sdk.aeyvision.com