w3w-swift-components-ocr

Overview

A Swift component library for what3words OCR. These components can work with either what3words' OCR SDK, or with iOS' Vision Framework.

what3words OCR XCFramework

If you want to use what3words' OCR XCFramework W3WOcrSdk.xcframework, please contact what3words to get it. Otherwise this component works fine on it's own and employs iOS's Vision Framework for the OCR.

Swift Package Manager

Use Swift Package Manager and add the URL below:

https://github.com/what3words/w3w-swift-components-ocr.git

Import the libraries wherever you use the components:

import W3WSwiftComponentsOcr

Info.plist

You must set the camera permission in your app's Info.plist:

Using The Component

The component constructor needs an OCR object.

Using the API with iOS' Vision Framework:

Our W3WOcrNative class that uses iOS' Vision Framework requires our API (or SDK) to be passed into the constructor.

  let api = What3WordsV4(apiKey: "YourApiKey")
  let ocr = W3WOcrNative(api)
  let ocrViewController = W3WOcrViewController(ocr: ocr)

Using the SDK with what3words' OCR SDK:

The what3words OCR SDK requires only a path to the OCR data files, and optionally a language parameter (ISO 2 letter language code).

  let ocr = W3WOcr(dataPath: "/path/to/ocr/datafiles", language: "en")
  let ocrViewController = W3WOcrViewController(ocr: ocr)

Typical Usage

Here's a typical use example set in a UIViewController's IBOutlet function that is connected to a UIButton (presuming the initialisation code above was used somewhere in the class):

@IBAction func scanButtonPressed(_ sender: Any) {

    let ocrViewController = W3WOcrViewController(ocr: ocr, w3w: api)
    
    // show the component
    present(ocrViewController, animated: true)
    
    // start the component
    ocrViewController.start()
    
    // when the user taps on a suggestion, stop and dismiss the component
    ocrViewController.onSuggestionSelected = { suggestion in
      print(suggestion)
      
      ocrViewController.stop()
      ocrViewController.dismiss(animated: true)
    }
    
    ocrViewController.onError = { error in
      print(error)
    }

}

Example Code

An example called OcrComponent can be found here in the our samples repository.

Customisation

If you want to use custom fonts, layout or colours, you can use a convenience function to set all the values:

import W3WThemes

let theme = W3WTheme.forOcr( 
  backgroundColor:            UIColor.white.w3wColor,
  bottomSheetBackgroundColor: UIColor.systemBackground.w3wColor,
  cameraBackgroundColor:      UIColor.darkGray.w3wColor,
  headerTextColor:            UIColor.red.w3wColor,
  brandColor:                 W3WColor.red,
  addressTextColor:           UIColor.black.w3wColor,
  footnoteTextColor:          UIColor.secondaryLabel.w3wColor,
  errorTextColor:             UIColor.red.w3wColor,
  fonts:                      W3WFonts(font: UIFont(name: "Courier", size: 24.0)),
  defaultLineColor:           UIColor.gray.w3wColor,
  successLineColor:           UIColor.green.w3wColor,
  errorLineColor:             UIColor.red.w3wColor,
  defaultLineThickness:       2.0,
  boldLineThickness:          1.0,
  defaultLineLength:          .large,
  boldLineLength:             .medium,
  withCornerRadius:           true,
  padding:                    .fine
)

// make the component
let ocrViewController = W3WOcrViewController(ocr: ocr, theme: theme, w3w: api)

The colours are specified using our custom W3WColor class, but you can use UIColor and suffix with .w3wColor and it will convert to our type.