iOS Mathpix API client, installable via cocoapods.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
MathpixClient reduce image quality to faster response Dec 29, 2017



MathpixClient is a simple wrapper to get and recognize images by mathpix server


To run the example project, clone the repo, and run pod install from the Example directory first.



MathpixClient is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "MathpixClient"

and run

pod install


Set api keys:

import MathpixClient

MathpixClient.setApiKeys(appId: "demo_app", appKey: "demo_key")

You can request an API key for free from

Launch camera:

The easiest way to use Mathpix on iOS is to launch our camera controller which can be done in a single line of code!

MathpixClient.launchCamera(source: self,
                           outputFormats: [FormatLatex.simplified],
                           backButtonCallback: {
                                print("back button pressed") },
                           completion: { (error, result) in
                                print("complete") })

Recognize images:

If you want to use a custom camera controller, you can still use the MathpixClient to recognize images:

MathpixClient.recognize(image: UIImage(named: "equation")!, outputFormats: [FormatLatex.simplified]) { (error, result) in
    print(result ?? error)

Launch camera with custom UI/UX properties:

You can fine tune the camera controller we provide using the MathCaptureProperties instance:

let properties = MathCaptureProperties(captureType: .gesture,
                                               requiredButtons: [.flash, .back],
                                               errorHandling: true)
MathpixClient.launchCamera(source: self,
                           outputFormats: [FormatLatex.simplified],
                           withProperties: properties,
                           backButtonCallback: {
                                print("back button pressed") },
                           completion: { (error, result) in
                                print("complete") })

Subclass MathCaptureViewController

If you need more control, you can subclass MathCaptureViewController.

class CustomCameraViewController: MathCaptureViewController {
    override func viewDidLoad() {

        // Add your UI elements here


We now describe how to pass options to the Mathpix API via the iOS Mathpix SDK. For more information regarding these options, please refer to the API documentation at:


Protocol represents additional field "formats" in request body. Requested as parameter outputFormats array. You can set several values:


The latex field, if present, is one of “raw” (result is the unmodified OCR output), “defaultValue” (result is OCR output with extraneous spaces removed), or “simplified” (result has spaces removed, operator shortcuts, and is split into lists where appropriate):

public enum FormatLatex {
    case raw, defaultValue, simplified


The mathml field, if present and set to on, indicates the server should add a mathml field to the JSON result that is a string containing the MathML markup for the recognized math. In the case of an incompatible result, the server will instead add a mathml_error:

public enum FormatMathml {
    case on


The wolfram field, if present and set to on, indicates the server should add a wolfram field to the JSON result that is a string compatible with the Wolfram Alpha engine. In the case of an incompatible result, the server will instead add a wolfram_error field:

public enum FormatWolfram {
    case on


The struct to incapsulate MathCaptureViewController properties. You can customize some UI/UX values:

The color of crop overlay bounds

let cropColor: UIColor

The icon of shutter button

let shutterIcon : UIImage?

The icon of flash button

let flashIcon : UIImage?

The icon of back button

let backIcon : UIImage?

The icon of cancel request button

let cancelIcon : UIImage?

The type of RecognitionAnimator. Used to provide animation for recognition process

let animatorType : RecognitionAnimator.Type

The type of UI capture action

let captureType: CaptureType

public enum CaptureType {
    /// Tap gesture is used to capture image.
    case gesture
    /// Shutter button is used to capture image.
    case button

The buttons which will be presented in instantiated MathCaptureViewController

let requiredButtons: [MathCaptureButton]

 public enum MathCaptureButton {
    /// Back button
    case back
    /// Flash button
    case flash

The size of shutter button

let bigButtonSize: CGSize

The size of buttons

let smallButtonSize: CGSize

The crop area insets

let cropAreaInsets: UIEdgeInsets

If enabled then errors will be handled by capture controller

let errorHandling: Bool


You can subclass it to get more control. See example app.

Error handling

For simple internal error handling add errorHandling: true parameter to MathCaptureProperties. Errors that you can get in callbacks represents by two main types:


Error type will be thrown if network failed

public enum NetworkError: Error {

    /// Unknown or not supported error.
    case unknown
    /// Not connected to the internet.
    case notConnectedToInternet
    /// International data roaming turned off.
    case internationalRoamingOff
    /// Cannot reach the server.
    case notReachedServer
    /// Connection is lost.
    case connectionLost
    /// Incorrect data returned from the server.
    case incorrectDataReturned
    /// Request canceled.
    case requestCanceled


Error type will be thrown if recognition failed

public enum RecognitionError: Error {

    /// Failed parse JSON, incorrect data returned
    case failedParseJSON
    /// Server can't recognize image as math
    case notMath(description: String)
    /// Invalid credentials, set correct api keys
    case invalidCredentials

Example Error Handling:

MathpixClient.launchCamera(source: self,
                           outputFormats: [FormatLatex.simplified],
                                { (error, result) in
                                    if let error = error as? NetworkError {
                                    } else if let error = error as? RecognitionError {
                                    } else if let error = error {


To set labels or error messages add Localizable.strings file to your project if you haven't it. Then change values:

// Errors
"Error credintials title" = "Error";
"Error credintials messages" = "Invalid credentials";
"Error capture title" = "Error capture";
"Error capture message" = "Capture image error";
"Error timeout title" = "Timeout error";
"Error timeout message" = "Send image timeout";
"Error no connection tittle" = "Network error";
"Error no connection message" = "No internet connection";
"Error parse title" = "Error parse";
"Error parse message" = "Error parse json";

// Tap info label
"Tap info label text" = "Tap anywhere to take a picture";


MathpixClient is available under the MIT license. See the LICENSE file for more info.