API Reference

The SDK functionality is exposed through the Snapshot object. This reference provides detailed information about all available methods, parameters, and return values.

Core Methods

Snapshot.enginePrepare()

Initializes the SDK engine. This method must be called once before any processing can be done.

Thread: Must be called on the main thread

Signature:

fun enginePrepare(
    context: Context,
    token: String,
    licenseKey: String,
    writablePath: String,
    assetManager: AssetManager
): Boolean

Parameters:

• context: The application context
• token: Your ParkPow API token (40 characters) - See Getting Started
• licenseKey: Your Snapshot SDK license key (10 characters, starts with platerec_) - See Getting Started
• writablePath: A path to a writable directory for the SDK to store cache files
• assetManager: The application's AssetManager to load the models

Returns: true if initialization was successful, false otherwise

Example:

val success = Snapshot.enginePrepare(
    context = applicationContext,
    token = "YOUR_TOKEN", // See Getting Started for credential setup
    licenseKey = "YOUR_LICENSE_KEY", // See Getting Started for credential setup
    writablePath = applicationContext.filesDir.absolutePath,
    assetManager = applicationContext.assets
)

if (!success) {
    Log.e("PlateRecognizer", "SDK initialization failed")
    // Handle initialization failure
}

---

Snapshot.engineProc()

Processes a single image file for license plate recognition.

Thread: Thread-safe, should be called on a background thread

Signature:

fun engineProc(
    filename: String,
    configJson: String,
    regions: Array<String>,
    doMmc: Boolean,
    doDirection: Boolean,
    cameraId: String,
    timestamp: String
): String

Parameters:

• filename: The absolute path to the image file
• configJson: A JSON string for advanced configuration (use "{}" for defaults). See Configuration Options for details.
• regions: An array of country codes to look for (e.g., arrayOf("us", "br"))
• doMmc: If true, enables Make, Model, and Color detection (requires MMC package)
• doDirection: If true, enables vehicle direction detection (requires MMC package)
• cameraId: An optional identifier for the camera that captured the image
• timestamp: An optional timestamp for when the image was captured

Returns: A JSON string containing the recognition results. Refer to Response Format for details.

Example with MMC Features:

val resultJson = Snapshot.engineProc(
    filename = "/path/to/your/image.jpg",
    configJson = "{\"threshold_d\": 0.2, \"region\": \"us\"}",
    regions = arrayOf("us", "ca"),
    doMmc = true, // Requires MMC package
    doDirection = true, // Requires MMC package
    cameraId = "entrance-camera",
    timestamp = System.currentTimeMillis().toString()
)

Example without MMC Features:

val resultJson = Snapshot.engineProc(
    filename = "/path/to/your/image.jpg",
    configJson = "{}",
    regions = arrayOf("us"),
    doMmc = false, // No MMC package required
    doDirection = false, // No MMC package required
    cameraId = "basic-camera",
    timestamp = System.currentTimeMillis().toString()
)

---

Snapshot.engineOnStop()

Saves the SDK state. Call this when your application is shutting down to ensure all data is saved correctly.

Thread: Must be called on the main thread

Signature:

fun engineOnStop(context: Context)

Parameters:

• context: The application context

Example:

override fun onDestroy() {
    super.onDestroy()
    Snapshot.engineOnStop(this)
}

MMC Package Requirements

The Make, Model, Color (MMC) and direction detection features require the MMC package.

warning

If the MMC package is not enabled:

• Set doMmc = false and doDirection = false
• The response will not include vehicle and direction fields
• Using these features without the MMC package may result in runtime errors

To enable MMC features, upgrade your license or purchase one that includes the MMC package.

Configuration Options

JSON Configuration

The configJson parameter accepts a JSON string with advanced configuration options:

{
  "threshold_d": 0.1,
  "threshold_o": 0.3,
  "detect_alphabets": ["A-Z", "0-9"],
  "region": "us"
}

Configuration Parameters:

• threshold_d: Detection threshold (default: 0.1)
• threshold_o: OCR threshold (default: 0.3)
• detect_alphabets: Array of character sets to detect
• region: Country/region code for specialized processing

For a complete list of all available options, refer to the Snapshot SDK Engine Configuration Options.

Supported Regions

The regions parameter accepts an array of country codes:

val regions = arrayOf(
    "us",    // United States
    "ca",    // Canada
    "br",    // Brazil
    "mx",    // Mexico
    "eu",    // European Union
    "uk",    // United Kingdom
    "au",    // Australia
    "nz",    // New Zealand
    "jp",    // Japan
    "kr"     // South Korea
)

For a complete list of supported regions, refer to the Country Codes.

Response Format

Success Response

{
  "processing_time": 0.123,
  "results": [
    {
      "box": {
        "xmin": 316,
        "ymin": 187,
        "xmax": 466,
        "ymax": 227
      },
      "plate": "ABC123",
      "score": 0.901,
      "candidates": [
        {
          "score": 0.901,
          "plate": "ABC123"
        }
      ],
      "vehicle": {
        "make": "Toyota",
        "model": "Camry",
        "color": "white",
        "score": 0.85
      },
      "direction": {
        "angle": 45,
        "confidence": 0.78
      }
    }
  ],
  "usage": {
    "calls": 1,
    "max_calls": 1000
  }
}

Response Fields: The response JSON is based on the Snapshot SDK API Response with the following fields:

• processing_time: Time taken to process the image in seconds
• results: Array of detected license plates
  • box: Bounding box coordinates of the detected plate
    • xmin, ymin: Top-left corner coordinates
    • xmax, ymax: Bottom-right corner coordinates
  • plate: The recognized license plate text
  • score: Confidence score (0.0 to 1.0)
  • candidates: Alternative plate possibilities with scores
  • vehicle: Vehicle information (when doMmc = true and MMC package is available)
    • make: Vehicle manufacturer
    • model: Vehicle model
    • color: Vehicle color
    • score: Confidence score for vehicle detection
  • direction: Vehicle direction information (when doDirection = true and MMC package is available)
    • angle: Direction angle in degrees
    • confidence: Confidence score for direction detection
• usage: API usage statistics. Note that this is available only when using the Snapshot SDK for Android.
  • calls: Number of calls made
  • max_calls: Maximum allowed calls

Error Handling

Error Response Format

{
  "error": "ERR0001",
  "error_message": "Invalid or expired license key"
}

Common Error Codes

Error Code	Description	Solution
ERR0001	Invalid or expired license key	Check your license key and ensure it's active
ERR0002	Network error during the initial license check	Ensure internet connectivity for initial setup
ERR0003	Invalid image format or size	Use JPEG or PNG images with reasonable dimensions
ERR0016	Device fingerprint does not match the license	License key is tied to a specific device
ERR0020	Insufficient RAM or storage	Close other apps or use a device with more RAM
ERR0030	Failed to load the machine learning models from assets	Ensure model files are properly included
ERR0040	Camera initialization error	Check camera permissions and availability

Exception Handling

Always wrap engineProc() calls in try-catch blocks:

try {
    val result = Snapshot.engineProc(
        filename = "/path/to/image.jpg",
        configJson = "{}",
        regions = arrayOf("us"),
        doMmc = false,
        doDirection = false,
        cameraId = "default",
        timestamp = System.currentTimeMillis().toString()
    )

    // Check for errors in JSON response
    val jsonObject = JSONObject(result)
    if (jsonObject.has("error")) {
        val errorCode = jsonObject.getString("error")
        Log.e("PlateRecognizer", "Recognition error: $errorCode")
        return
    }

    // Process successful result
    processRecognitionResult(jsonObject)

} catch (e: Exception) {
    Log.e("PlateRecognizer", "Recognition failed", e)
}

Performance Considerations

Image Requirements

• Resolution: Recommended between 800x600 and 1920x1080
• Format: JPEG and PNG formats supported
• Quality: Ensure license plate is in focus and clearly readable
• Lighting: Good, consistent lighting is crucial
• Angle: Avoid extreme angles for best results

Memory Management

• Process one image at a time per thread
• Downsample very large images before processing
• Call engineOnStop() in your main Activity's onDestroy() method

Threading Guidelines

• enginePrepare() and engineOnStop() must be called on the main thread
• engineProc() is thread-safe and should be called on a background thread
• Use proper thread synchronization when processing multiple images

Comprehensive Usage Examples

Complete Integration Example

danger

Replace YOUR_TOKEN and YOUR_LICENSE_KEY with your actual credentials. See Obtaining Your Credentials for details.

// Initialize SDK
val success = Snapshot.enginePrepare(
    context = applicationContext,
    token = "YOUR_TOKEN", // See Getting Started for credential setup
    licenseKey = "YOUR_LICENSE_KEY", // See Getting Started for credential setup
    writablePath = applicationContext.filesDir.absolutePath,
    assetManager = applicationContext.assets
)

if (success) {
    // Process image
    Thread {
        val result = Snapshot.engineProc(
            filename = "/path/to/image.jpg",
            configJson = "{}",
            regions = arrayOf("us"),
            doMmc = false,
            doDirection = false,
            cameraId = "default",
            timestamp = System.currentTimeMillis().toString()
        )

        // Handle result on main thread
        Handler(Looper.getMainLooper()).post {
            processResult(result)
        }
    }.start()
}

Advanced Usage with Vehicle Detection

warning

This example uses doMmc = true and doDirection = true, which require the MMC (Make, Model, Color) package. See MMC Package Requirements for details.

val result = Snapshot.engineProc(
    filename = imagePath,
    configJson = """
    {
        "threshold_d": 0.2,
        "threshold_o": 0.4,
        "region": "us"
    }
    """,
    regions = arrayOf("us", "ca"),
    doMmc = true, // Requires MMC package
    doDirection = true, // Requires MMC package
    cameraId = "parking-entrance",
    timestamp = System.currentTimeMillis().toString()
)

This completes the API reference for the Snapshot SDK for Android. For more information, see the Getting Started and Integration Guide sections.