Pemecahan Masalah (Troubleshooting)

Skenario kendala umum di berbagai platform beserta langkah-langkah solusinya.

1. Berkas & Aset Model Tidak Ditemukan

Gejala

Muncul eksepsi saat inisialisasi: Failed to initialize RustO with config, Model asset not found, atau FileNotFoundException.

Penyebab

Mesin tidak dapat menemukan file det.rten, rec.rten, atau dict.txt pada direktori kerja aktif atau bundel aplikasi.

Solusi

• Rust / CLI / C FFI: Pastikan path relatif dihitung dari direktori kerja aktif saat ini, atau gunakan path absolut (contoh: /usr/share/models/det.rten).
• .NET / C#: Pastikan Anda telah memasang paket model NuGet (misal RustODotnet.Models.PPOCRv6.Tiny) atau menyalin berkas model dengan opsi <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory> pada file .csproj.
• iOS / Swift: Pastikan Anda telah menambahkan pod 'RustO-Models-PPOCRv6-Tiny' pada ios/Podfile dan menjalankan pod install.
• Android: Pastikan paket rusto-models-ppocrv6-tiny dideklarasikan di app/build.gradle dan Anda meneruskan Context Android ke RustO.initialize(context).

2. Android: UnsatisfiedLinkError atau Simbol JNI Tidak Ditemukan

Gejala

java.lang.UnsatisfiedLinkError: dlopen failed: library "librusto.so" not found.

Solusi

Pastikan konfigurasi build.gradle aplikasi Anda tidak memfilter ABI yang didukung. Tambahkan filter ABI standar pada android.defaultConfig.ndk:

android {
    defaultConfig {
        ndk {
            abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86_64', 'x86'
        }
    }
}

3. React Native: "The package '@rustors/react-native' doesn't seem to be linked"

Gejala

Kesalahan saat memanggil initialize() atau detectText() pada React Native.

Solusi

1. Bare React Native:
   • iOS: Jalankan cd ios && pod install, lalu kompilasi ulang dengan npm run ios.
   • Android: Bersihkan cache Gradle dengan cd android && ./gradlew clean, lalu kompilasi ulang.
2. Expo: Pustaka native C/Rust kustom tidak dapat dijalankan di Expo Go bawaan. Anda harus menggunakan development build:

   npx expo run:ios
   # atau
   npx expo run:android
   

4. Kehabisan Memori (OOM) pada Foto Kamera Resolusi Tinggi

Gejala

Aplikasi mengalami crash karena kehabisan memori RAM saat memindai foto kamera beresolusi sangat besar (48MP, 108MP).

Solusi

Batasi dimensi maksimum gambar pada OcrRunOptions sebelum gambar diproses oleh jaringan inferensi:

const safeOptions = {
  maxSideLen: 1600, // Menurunkan skala dimensi sebelum alokasi memori
  detection: {
    limitSideLen: 960,
    limitType: 'max',
  },
};

5. Teks Struk Termal Pudar atau Dot-Matrix Tidak Terdeteksi

Gejala

Teks pada kertas termal atau struk dot-matrix terlewat atau terpotong-potong.

Solusi

Aktifkan dilatasi morfologi 2x2 dan turunkan ambang binarisasi:

const receiptOptions = {
  textScore: 0.45,
  postprocess: {
    useDilation: true, // Menyambungkan kembali karakter yang putus
    threshold: 0.25, // Menurunkan batas binarisasi piksel
    unclipRatio: 2.2, // Memperluas area batas poligon
  },
};

6. Web & React: WebAssembly Terblokir atau Pelanggaran Kebijakan Keamanan Konten (CSP)

Gejala

Konsol peramban menampilkan kesalahan saat inisialisasi @rustors/web atau @rustors/react:

• EvalError: Refused to compile or instantiate WebAssembly module because 'wasm-unsafe-eval' is not an allowed source of script...
• Refused to connect to 'https://cdn.jsdelivr.net/...' because it violates the following Content Security Policy directive...
• SecurityError: Failed to construct 'Worker': Script at 'blob:...' cannot be accessed from origin...

Penyebab

Konfigurasi header server perusahaan atau pembatasan ketat Content Security Policy (CSP) memblokir kompilasi bytecode WebAssembly, unduhan aset dari CDN, atau inisiasi Web Worker.

Solusi

Tambahkan aturan CSP yang diperlukan pada header HTTP server (atau tag <meta http-equiv="Content-Security-Policy">):

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval' https://cdn.jsdelivr.net;
  connect-src 'self' https://cdn.jsdelivr.net blob:;
  worker-src 'self' blob:;
  img-src 'self' data: blob:;

1. Kompilasi WebAssembly: Peramban modern Chromium, Firefox, dan Safari mewajibkan direktif 'wasm-unsafe-eval' (atau 'unsafe-eval') di bawah script-src untuk memanggil WebAssembly.instantiate().
2. Aset CDN: Jika model atau file .wasm dimuat dari jsDelivr, sertakan https://cdn.jsdelivr.net pada script-src dan connect-src.
3. Fallback Tanpa Web Worker: Jika direktif worker-src tidak dapat diubah, atur @rustors/web untuk berjalan di thread utama:

   await initialize({
     worker: false, // Menjalankan inferensi sinkron di thread utama
     ...
   });