BitmapRegionDecoder Directory Reference

Directories
	dart
	java
	kotlin
	objc
	swift

Detailed Description

This directory contains comprehensive examples demonstrating the usage of the Navigine SDK's BitmapRegionDecoder across all supported platforms.

Overview

The BitmapRegionDecoder is responsible for decoding bitmap images from byte arrays and extracting specific regions. It provides functionality for:

• Image Decoding: Creating decoders from raw image data (PNG, JPG, SVG)
• Region Extraction: Decoding specific rectangular regions from images
• Sample Size Control: Optimizing memory usage with subsampling
• Performance Optimization: Efficient handling of large images

Key Components

BitmapRegionDecoder

The main class for bitmap region decoding operations:

• newInstance() - Create decoder from byte array data
• decodeRegion() - Decode specific rectangular region with sample size control

Rectangle

Represents a rectangular region for image decoding:

• x, y - Origin coordinates
• width, height - Rectangle dimensions

Platform-Specific Files

Dart/Flutter

• dart/bitmap_region_decoder_example.dart - Complete example with all BitmapRegionDecoder features

Java

• java/BitmapRegionDecoderExample.java - Java implementation with comprehensive API coverage

Kotlin

• kotlin/BitmapRegionDecoderExample.kt - Kotlin implementation using coroutines for async operations

Objective-C

• objc/BitmapRegionDecoderExample.h - Header file with interface declarations
• objc/BitmapRegionDecoderExample.m - Implementation with all BitmapRegionDecoder methods

Swift

• swift/BitmapRegionDecoderExample.swift - Swift implementation with modern syntax

Key Documentation Tags

BitmapRegionDecoder Methods

• [platform_BitmapRegionDecoder_newInstance] - Creating decoder instances
• [platform_BitmapRegionDecoder_decodeRegion] - Decoding image regions
• [platform_BitmapRegionDecoder_decodeRegion_sampleSize] - Decoding with sample size control
• [platform_BitmapRegionDecoder_decodeRegion_multiple] - Decoding multiple regions

Rectangle Properties

• [platform_Rectangle_constructor] - Creating rectangles
• [platform_Rectangle_getX] - Getting X coordinate
• [platform_Rectangle_getY] - Getting Y coordinate
• [platform_Rectangle_getWidth] - Getting width
• [platform_Rectangle_getHeight] - Getting height

Common Usage Patterns

1. Creating a Decoder

// Load image data from file or network
Uint8List imageData = loadImageData();
 
// Create decoder instance
BitmapRegionDecoder decoder = BitmapRegionDecoder.newInstance(imageData);

2. Defining Regions

// Create rectangle for region extraction
Rectangle region = Rectangle(100, 100, 400, 300); // x, y, width, height
 
// Access rectangle properties
int x = region.x;
int y = region.y;
int width = region.width;
int height = region.height;

3. Decoding Regions

// Decode full resolution region
ImageWrapper image = decoder.decodeRegion(region, 1);
 
// Decode with subsampling for memory optimization
ImageWrapper thumbnail = decoder.decodeRegion(region, 4); // 1/4 size

4. Multiple Region Decoding

// Define multiple regions
List<Rectangle> regions = [
  Rectangle(0, 0, 256, 256),      // Top-left
  Rectangle(256, 0, 256, 256),    // Top-right
  Rectangle(0, 256, 256, 256),    // Bottom-left
  Rectangle(256, 256, 256, 256),  // Bottom-right
];
 
// Decode each region
for (Rectangle region in regions) {
  ImageWrapper image = decoder.decodeRegion(region, 1);
   public processImage(image);
}

5. Performance Optimization

// Test different sample sizes for performance
Rectangle largeRegion = Rectangle(0, 0, 1024, 768);
List<int> sampleSizes = [1, 2, 4, 8, 16];
 
for (int sampleSize in sampleSizes) {
  final stopwatch = Stopwatch()..start();
  ImageWrapper image = decoder.decodeRegion(largeRegion, sampleSize);
  stopwatch.stop();
 
  print("Sample size $sampleSize: ${stopwatch.elapsedMilliseconds}ms");
}

6. Error Handling

try {
  BitmapRegionDecoder decoder = BitmapRegionDecoder.newInstance(invalidData);
  ImageWrapper image = decoder.decodeRegion(region, 1);
} catch (e) {
  print("Failed to decode image: $e");
}

Running Examples

Dart/Flutter

cd examples/BitmapRegionDecoder/dart
dart bitmap_region_decoder_example.dart

Java

cd examples/BitmapRegionDecoder/java
javac BitmapRegionDecoderExample.java
java BitmapRegionDecoderExample

Kotlin

cd examples/BitmapRegionDecoder/kotlin
kotlinc BitmapRegionDecoderExample.kt -include-runtime -d BitmapRegionDecoderExample.jar
java -jar BitmapRegionDecoderExample.jar

Objective-C

cd examples/BitmapRegionDecoder/objc
clang -framework Foundation BitmapRegionDecoderExample.m -o BitmapRegionDecoderExample
./BitmapRegionDecoderExample

Swift

cd examples/BitmapRegionDecoder/swift
swift BitmapRegionDecoderExample.swift

Advanced Features

Sample Size Optimization

The sample size parameter controls subsampling for memory optimization:

// Full resolution (sample size 1)
ImageWrapper fullRes = decoder.decodeRegion(region, 1);
 
// Half resolution (sample size 2)
ImageWrapper halfRes = decoder.decodeRegion(region, 2);
 
// Quarter resolution (sample size 4)
ImageWrapper quarterRes = decoder.decodeRegion(region, 4);

Rectangle Manipulation

Create different rectangle variations for various use cases:

// Base rectangle
Rectangle base = Rectangle(100, 100, 200, 150);
 
// Variations
Rectangle halfWidth = Rectangle(base.x, base.y, base.width / 2, base.height);
Rectangle halfHeight = Rectangle(base.x, base.y, base.width, base.height / 2);
Rectangle centered = Rectangle(base.x + 50, base.y + 25, base.width - 100, base.height - 50);

Multiple Image Formats

The decoder supports various image formats:

// PNG image
Uint8List pngData = loadPngData();
BitmapRegionDecoder pngDecoder = BitmapRegionDecoder.newInstance(pngData);
 
// JPEG image
Uint8List jpegData = loadJpegData();
BitmapRegionDecoder jpegDecoder = BitmapRegionDecoder.newInstance(jpegData);
 
// SVG image (raw string)
Uint8List svgData = loadSvgData();
BitmapRegionDecoder svgDecoder = BitmapRegionDecoder.newInstance(svgData);

Performance Considerations

Memory Usage

• Use appropriate sample sizes for large images
• Decode only the regions you need
• Consider the trade-off between quality and memory usage

Processing Speed

• Larger sample sizes decode faster but with lower quality
• Multiple small regions may be faster than one large region
• Profile your specific use case for optimal performance

Error Handling

• Always validate image data before creating decoders
• Handle invalid rectangle coordinates gracefully
• Implement fallback strategies for failed decodings

Notes

• All examples demonstrate the same functionality across platforms
• Image data is typically loaded from files or network sources
• Sample size must be a positive integer (1 = full resolution)
• Rectangle coordinates are zero-based
• The decoder supports PNG, JPG, and SVG formats
• Decoded images are returned as ImageWrapper objects
• Performance varies significantly with image size and sample size
• Memory usage scales with decoded image dimensions
• Error handling is important for robust applications