@cognivision.io/react-native-cogni-ml

⚡️ React Native ML SDK — Run computer vision models on iOS devices with Turbo Modules

Run on-device object detection with your custom-trained models. Built on React Native's new Turbo Module architecture for optimal performance.

✨ Features

• 🎯 Object Detection - Detect objects in images with high accuracy
• ⚡️ Turbo Module Architecture - Built on React Native's new architecture for better performance
• 📱 Local Inference - Run models on-device, no API calls needed after model download
• 🔒 Privacy First - Your images never leave the device
• 📦 TypeScript Support - Full type definitions included
• 🔄 Backward Compatible - Works with both old and new React Native architectures

📋 Requirements

• React Native >= 0.68
• iOS >= 15.4
• Xcode >= 14
• Min Deployment Target >= 18.6
• A Cogni Vision API key

🚀 Installation

npm install @cognivision.io/react-native-cogni-ml
# or
yarn add @cognivision.io/react-native-cogni-ml

iOS Setup

cd ios && pod install && cd ..

Enable New Architecture (Optional - Recommended)

For full Turbo Module benefits, enable the New Architecture in ios/Podfile:

ENV['RCT_NEW_ARCH_ENABLED'] = '1'

Then reinstall pods and rebuild:

cd ios && pod install && cd ..
npx react-native run-ios

Note: The package works with both old and new architectures automatically!

📖 Usage

Basic Example

import CogniML from '@cognivision.io/react-native-cogni-ml';

async function runDetection() {
  // 1. Initialize with your API key, workspace URL, model ID, and version
  await CogniML.initialize(
    'YOUR_API_KEY',
    'YOUR_WORKSPACE_URL',
    'your-model-id',
    1
  );

  // 2. Load your model
  await CogniML.loadModel();

  // 3. Run detection on an image
  const result = await CogniML.detectObjects('file:///path/to/image.jpg');

  console.log(`Found ${result.predictions.length} objects`);
  result.predictions.forEach((pred) => {
    console.log(`${pred.class}: ${(pred.confidence * 100).toFixed(1)}%`);
  });
}

Complete Example with Image Picker

import React, { useEffect, useState } from 'react';
import {
  View,
  Button,
  Image,
  Text,
  StyleSheet,
  ScrollView,
} from 'react-native';
import CogniML from '@cognivision.io/react-native-cogni-ml';
import { launchImageLibrary } from 'react-native-image-picker';

function App() {
  const [ready, setReady] = useState(false);
  const [imageUri, setImageUri] = useState(null);
  const [predictions, setPredictions] = useState([]);

  useEffect(() => {
    async function setup() {
      try {
        await CogniML.initialize(
          'YOUR_API_KEY',
          'YOUR_WORKSPACE_URL',
          'your-model-id',
          1
        );
        await CogniML.loadModel();
        setReady(true);
        console.log('✅ CogniML ready!');
      } catch (error) {
        console.error('Setup failed:', error);
      }
    }
    setup();
  }, []);

  const pickAndDetect = async () => {
    const result = await launchImageLibrary({ mediaType: 'photo' });

    if (result.assets?.[0]?.uri) {
      setImageUri(result.assets[0].uri);

      const detections = await CogniML.detectObjects(result.assets[0].uri);

      setPredictions(detections.predictions);
      console.log(`Inference time: ${detections.inferenceTime}ms`);
    }
  };

  return (
    <ScrollView style={styles.container}>
      <Text style={styles.title}>CogniML Object Detection</Text>

      <Button
        title="Pick Image & Detect"
        onPress={pickAndDetect}
        disabled={!ready}
      />

      {imageUri && <Image source={{ uri: imageUri }} style={styles.image} />}

      {predictions.length > 0 && (
        <View style={styles.results}>
          <Text style={styles.resultsTitle}>
            Detections ({predictions.length})
          </Text>
          {predictions.map((pred, index) => (
            <View key={index} style={styles.prediction}>
              <Text style={styles.predClass}>{pred.class}</Text>
              <Text style={styles.predConf}>
                {(pred.confidence * 100).toFixed(1)}%
              </Text>
            </View>
          ))}
        </View>
      )}
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20 },
  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 },
  image: {
    width: '100%',
    height: 300,
    resizeMode: 'contain',
    marginVertical: 20,
  },
  results: { marginTop: 20 },
  resultsTitle: { fontSize: 18, fontWeight: 'bold', marginBottom: 10 },
  prediction: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    padding: 10,
    backgroundColor: '#f0f0f0',
    marginBottom: 5,
    borderRadius: 5,
  },
  predClass: { fontSize: 16, fontWeight: '600' },
  predConf: { fontSize: 16, color: '#666' },
});

export default App;

📚 API Reference

initialize(apiKey, workspaceURL, modelId, version): Promise<void>

Initialize the SDK. Must be called before any other methods.

Parameters:

• apiKey (string) - Your Cogni Vision API key
• workspaceURL (string) - Your workspace URL
• modelId (string) - Your model ID
• version (number) - The model version number

Example:

await CogniML.initialize(
  'your_api_key',
  'your_workspace_url',
  'your-model-id',
  1
);

loadModel(): Promise<ModelInfo>

Load the model configured during initialize(). The model is cached locally for offline use.

Returns:

{
  success: boolean;
  modelName?: string;
  modelType?: string;
}

Example:

const info = await CogniML.loadModel();
console.log(`Loaded: ${info.modelName}`);

detectObjects(imageUri: string): Promise<DetectionResult>

Run object detection on an image.

Parameters:

• imageUri (string) - Image URI (supports file://, data:image/..., http://, https://)

Returns:

{
  predictions: Array<{
    class: string; // Object class name
    confidence: number; // Confidence score (0-1)
    x: number; // Center X coordinate
    y: number; // Center Y coordinate
    width: number; // Bounding box width
    height: number; // Bounding box height
  }>;
  inferenceTime: number; // Time taken in milliseconds
}

Example:

const result = await CogniML.detectObjects('file:///path/to/image.jpg');
result.predictions.forEach((pred) => {
  console.log(`${pred.class} at (${pred.x}, ${pred.y})`);
});

unloadModel(): Promise<void>

Unload the current model to free up memory.

await CogniML.unloadModel();

isInitialized(): boolean

Check if the SDK has been initialized.

if (CogniML.isInitialized()) {
  console.log('Ready to load models');
}

isModelLoaded(): boolean

Check if a model is currently loaded.

if (CogniML.isModelLoaded()) {
  console.log('Ready to detect objects');
}

🖼️ Image URI Formats

| Format | Example | Use Case | | ---------- | ------------------------------- | -------------------------- | | File URI | file:///var/mobile/... | Images from device storage | | Data URI | data:image/jpeg;base64,... | Base64 encoded images | | HTTP/HTTPS | https://example.com/image.jpg | Remote images |

Recommendation: Use file:// URIs for best performance.

🏗️ Architecture

This package uses Turbo Modules for optimal performance:

Old Architecture (< RN 0.68):

JavaScript → JSON Bridge → Native Code

New Architecture (>= RN 0.68):

JavaScript → JSI (Direct) → Native Code

• Direct C++ bindings via JSI
• No JSON serialization overhead
• ~30% faster for inference calls
• Type-safe at compile time

The package automatically uses the best architecture available!

🚀 Performance

Performance on iPhone 12:

| Operation | Time | Notes | | ------------------------- | ---------- | --------------------------- | | Initialize | ~100ms | One-time setup | | Load Model (first time) | ~2-5s | Downloads and caches | | Load Model (cached) | ~500ms | Loads from local cache | | Inference (640x640 image) | ~100-300ms | Depends on model complexity |

📱 Platform Support

| Platform | Status | | -------- | -------------------------- | | iOS | ✅ Fully supported (15.4+) | | Android | ⏳ Coming soon |

🐛 Troubleshooting

Module not available after installation

cd ios
rm -rf Pods Podfile.lock build
pod install
cd ..
npx react-native run-ios

Build errors after installation

cd ios
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf Pods Podfile.lock build
pod install --repo-update
cd ..
npx react-native run-ios

📄 License

MIT License - see LICENSE file for details

Made with ⚡️ and ☕️