OCR Text Detection and Extraction

Cloudinary is a cloud-based service that provides an end-to-end image and video management solution including uploads, storage, transformations, optimizations and delivery. It offers a rich set of image transformation capabilities, including cropping, overlays, graphic improvements, and a large variety of special effects.

The OCR Text Detection and Extraction add-on, powered by the Google Vision API, integrates seamlessly with Cloudinary's upload and transformation functionality. It extracts all detected text from images, including multi-page documents like TIFFs and PDFs.

You can use the extracted text directly for a variety of purposes, such as organizing or tagging images. Additionally, you can take advantage of special OCR-based transformations, such as blurring, pixelating, or overlaying other images on all detected text with simple transformation parameters. You can also use the add-on to ensure that important texts aren't cut off when you crop your images.

You can use the add-on in normal mode for capturing text elements within a photograph or other graphical image, or in document mode for capturing dense text such as a scan of a document. If you expect images to include non-latin characters, you can instruct the add-on to analyze the image for a specific language.

The following example uses the normal mode of the OCR add-on to pixelate the license plate text in this car photograph:

Original

Pixelated

URL Ruby PHP Python Node.js Java JS jQuery React Vue.js Angular .NET iOS Android Kotlin All

URL:

https://res.cloudinary.com/demo/image/upload/c_crop,g_west,h_1440,w_1520,x_50/e_pixelate_region:15,g_ocr_text/black_car.jpg

Ruby:

cl_image_tag("black_car.jpg", :transformation=>[
  {:gravity=>"west", :height=>1440, :width=>1520, :x=>50, :crop=>"crop"},
  {:effect=>"pixelate_region:15", :gravity=>"ocr_text"}
  ])

PHP (cloudinary_php v2.x):

(new ImageTag('black_car.jpg'))
  ->resize(Resize::crop()->width(1520)
->height(1440)
  ->gravity(
  Gravity::compass(
  Compass::west()))
->x(50))
  ->effect(Effect::pixelate()->squareSize(15)
  ->region(
  Region::ocr())
  );

Library:

PHP (cloudinary_php v1.x (legacy)):

cl_image_tag("black_car.jpg", array("transformation"=>array(
  array("gravity"=>"west", "height"=>1440, "width"=>1520, "x"=>50, "crop"=>"crop"),
  array("effect"=>"pixelate_region:15", "gravity"=>"ocr_text")
  )))

Library:

Python:

CloudinaryImage("black_car.jpg").image(transformation=[
  {'gravity': "west", 'height': 1440, 'width': 1520, 'x': 50, 'crop': "crop"},
  {'effect': "pixelate_region:15", 'gravity': "ocr_text"}
  ])

Node.js:

cloudinary.image("black_car.jpg", {transformation: [
  {gravity: "west", height: 1440, width: 1520, x: 50, crop: "crop"},
  {effect: "pixelate_region:15", gravity: "ocr_text"}
  ]})

Java:

cloudinary.url().transformation(new Transformation()
  .gravity("west").height(1440).width(1520).x(50).crop("crop").chain()
  .effect("pixelate_region:15").gravity("ocr_text")).imageTag("black_car.jpg");

JS (js-url-gen v1.x):

new CloudinaryImage("black_car.jpg")
  .resize(
    crop()
      .width(1520)
      .height(1440)
      .gravity(compass("west"))
      .x(50)
  )
  .effect(
    pixelate()
      .squareSize(15)
      .region(ocr())
  );

Library:

JS (cloudinary-core v2.x (legacy)):

cloudinary.imageTag('black_car.jpg', {transformation: [
  {gravity: "west", height: 1440, width: 1520, x: 50, crop: "crop"},
  {effect: "pixelate_region:15", gravity: "ocr_text"}
  ]}).toHtml();

Library:

jQuery:

$.cloudinary.image("black_car.jpg", {transformation: [
  {gravity: "west", height: 1440, width: 1520, x: 50, crop: "crop"},
  {effect: "pixelate_region:15", gravity: "ocr_text"}
  ]})

React:

<Image publicId="black_car.jpg" >
  <Transformation gravity="west" height="1440" width="1520" x="50" crop="crop" />
  <Transformation effect="pixelate_region:15" gravity="ocr_text" />
</Image>

Vue.js:

<cld-image public-id="black_car.jpg" >
  <cld-transformation gravity="west" height="1440" width="1520" x="50" crop="crop" />
  <cld-transformation effect="pixelate_region:15" gravity="ocr_text" />
</cld-image>

Angular:

<cl-image public-id="black_car.jpg" >
  <cl-transformation gravity="west" height="1440" width="1520" x="50" crop="crop">
  </cl-transformation>
  <cl-transformation effect="pixelate_region:15" gravity="ocr_text">
  </cl-transformation>
</cl-image>

.NET:

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Gravity("west").Height(1440).Width(1520).X(50).Crop("crop").Chain()
  .Effect("pixelate_region:15").Gravity("ocr_text")).BuildImageTag("black_car.jpg")

iOS:

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setGravity("west").setHeight(1440).setWidth(1520).setX(50).setCrop("crop").chain()
  .setEffect("pixelate_region:15").setGravity("ocr_text")).generate("black_car.jpg")!, cloudinary: cloudinary)

Android:

MediaManager.get().url().transformation(new Transformation()
  .gravity("west").height(1440).width(1520).x(50).crop("crop").chain()
  .effect("pixelate_region:15").gravity("ocr_text")).generate("black_car.jpg");

Kotlin:

// This code example is not currently available.

Getting started

Before you can use the OCR Text Detection and Extraction add-on:

You must have a Cloudinary account. If you don't already have one, you can sign up for a free account.
Register for the add-on: make sure you're logged in to your account and then go to the Add-ons page. For more information about add-on registrations, see Registering for add-ons.
Keep in mind that many of the examples on this page use our SDKs. For SDK installation and configuration details, see the relevant SDK guide.
If you are new to Cloudinary, you may want to take a look at How to integrate Cloudinary in your app for a walk through on the basics of creating and setting up your account, working with SDKs, and then uploading, transforming and delivering assets.

Important

By default, delivery URLs that use this add-on either need to be signed or eagerly generated. You can optionally remove this requirement by selecting this add-on in the Allow unsigned add-on transformations section of the Security account settings in the Cloudinary console (the demo account has this setting applied to make the examples on this page easier to read and try out).

On this page:

Getting started
Extracting detected text
Blurring or pixelating detected text
Overlaying detected text with images
Text-based cropping
Signed URLs
Language support

Extracting detected text

You can return all text detected in an image file in the JSON response of any upload or update call.

The returned content includes a summary of all returned text and the bounding box coordinates of the entire captured text, plus a breakdown of each text element (an individual word or other set of characters without a space) captured and the bounding box of each such text element.

Requesting extracted text (upload/update methods)

To request inclusion of detected text in the response of your upload or update method call, set the ocr parameter to adv_ocr (for photos or images containing text elements) or adv_ocr:document (for best results on text-heavy images such as scanned documents).

For example, when using the upload method:

Ruby PHP Python Node.js Java .NET Android cURL CLI All

Ruby:

Cloudinary::Uploader.upload("concert_ticket.jpg",  
  :ocr => "adv_ocr")

PHP (cloudinary_php v2.x):

$cloudinary->uploadApi()->upload("concert_ticket.jpg", 
  ["ocr" => "adv_ocr"]);

Library:

PHP (cloudinary_php v1.x (legacy)):

\Cloudinary\Uploader::upload("concert_ticket.jpg", 
  ["ocr" => "adv_ocr"]);

Library:

Python:

cloudinary.uploader.upload("concert_ticket.jpg",
  ocr = "adv_ocr")

Node.js:

cloudinary.v2.uploader.upload("concert_ticket.jpg", 
  { ocr: "adv_ocr" },
  function(error, result) {console.log(result); });

Java:

cloudinary.uploader().upload("concert_ticket.jpg", 
  ObjectUtils.asMap("ocr", "adv_ocr"));

.NET:

var uploadParams = new ImageUploadParams()
{
  File = new FileDescription(@"concert_ticket.jpg"),
  Ocr = "adv_ocr"
};
var uploadResult = cloudinary.Upload(uploadParams);

Android:

MediaManager.get().upload("concert_ticket.jpg")
  .option("ocr", "adv_ocr").dispatch();

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=concert_ticket.jpg&ocr=adv_ocr&timestamp=173719931&api_key=436464676&signature=a781d61f86a6f818af'

CLI:

cld uploader upload "concert_ticket.jpg" ocr="adv_ocr"

Tip

You can use upload presets to centrally define a set of upload options including add-on operations to apply, instead of specifying them in each upload call. You can define multiple upload presets, and apply different presets in different upload scenarios. You can create new upload presets in the Upload page of the Management Console settings or using the upload_presets Admin API method. From the Upload page of the console settings, you can also select default upload presets to use for image, video, and raw API uploads (respectively) as well as default presets for image, video, and raw uploads performed via the Media Library UI.

Learn more: Upload presets

Or when using the update method:

Ruby PHP Python Node.js Java .NET CLI All

Ruby:

Cloudinary::Api.update("concert_ticket", 
  :ocr => "adv_ocr")

PHP (cloudinary_php v2.x):

$api->update("concert_ticket", 
  ["ocr" => "adv_ocr"]);

Library:

PHP (cloudinary_php v1.x (legacy)):

\Cloudinary\Api::update("concert_ticket", 
  ["ocr" => "adv_ocr"]);

Library:

Python:

cloudinary.api.update("concert_ticket",
  ocr = "adv_ocr")

Node.js:

cloudinary.v2.api.update("concert_ticket", 
  { ocr: "adv_ocr" },
  function(error, result) {console.log(result); });

Java:

cloudinary.api().update("concert_ticket", 
  ObjectUtils.asMap("ocr", "adv_ocr"));

.NET:

var updateParams = new UpdateParams("concert_ticket")
{
  Ocr = "adv_ocr"
};
var updateResult = cloudinary.Update(updateParams);

CLI:

cld admin update "concert_ticket" ocr="adv_ocr"

Extracted text in the JSON response

When you upload an image (or perform an update operation) with the ocr parameter set to adv_ocr or adv_ocr:document, the JSON response includes an ocr node under the info section.

The ocr node of the response includes the following:

The name of the OCR engine used by the add-on (adv_ocr)
The status of the OCR operation
The detected locale of the text
The outer bounding rectangle containing all of the detected text
A description listing the entirety of the detected text content, with a newline character (\n) separating groups of text
For multi-page files (e.g. PDFs), a node indicating the containing page
The bounding rectangle of each individual detected text element and the description (text content) of that individual element

For example, an excerpt from the ocr section of the JSON response from a scanned restaurant receipt image may look something like this:

"info": {
  "ocr": {
    "adv_ocr": {
      "status": "complete",
      "data": [
        { "textAnnotations": [
            { "locale": "en",
              "boundingPoly": {
                "vertices": [
                  { "y": 373,
                    "x": 297 },
                  { "y": 373,
                    "x": 1306 },
                  { "y": 2735,
                    "x": 1306 },
                  { "y": 2735,
                    "x": 297 }
                ]
              },
              "description": "CREDIT CARD VOUCHER\nANY RESTAURANT\nANYWHERE\n(69) 
                69696969\nDATE\n02/02/2014\nTIME\n11:11\nCARD TYPE\nMC\nACCT\n1234 1234 
                1234 1111\nTRANS KEY\nHYU87 89798234\nAUTH CODE:\n12345\nEXP 
                DATE:\n12/15\nCHECK:\n1341\nTABLE\n12\nSERVER\n34 
                MONIKA\nSubtotal\n$1969.69\nGratuity\nTotal\nSignature:\nCustomer Copy\n"
            },
            { "boundingPoly": {
                "vertices": [
                  { "y": 373,
                    "x": 561 },
                  { "y": 373,
                    "x": 726 },
                  { "y": 426,
                    "x": 726 },
                  { "y": 426,
                    "x": 561 }
                ]
              },
              "description": "CREDIT"
            },
            { "boundingPoly": {
                "vertices": [
                  {
        ...
        ...
        ...
}

Using extracted text to process images

Once you have extracted text in your response, you can access it based on the response structure.

Ruby PHP Python Node.js Java .NET CLI All

Ruby:

$result = $cloudinary->uploadApi()->upload(some_image_file_path, ["ocr" => "adv_ocr"]);
if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
}

PHP (cloudinary_php v2.x):

use Cloudinary\Cloudinary;

$cloudinary = new Cloudinary();
$uploader = $cloudinary->uploadApi();
$result = $upload(some_image_file_path, ["ocr" => "adv_ocr"]);

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
}

Library:

PHP (cloudinary_php v1.x (legacy)):

$result = \Cloudinary\Uploader::upload(some_image_file_path, ["ocr" => "adv_ocr"]);

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
}

Library:

Python:

result = cloudinary.uploader.upload(some_image_file_path, ocr='adv_ocr')
if result['info']['ocr']['adv_ocr']['status'] == 'complete':
    data = result['info']['ocr']['adv_ocr']['data']

Node.js:

let result = cloudinary.v2.uploader.upload('some_image_file_path', {ocr: 'adv_ocr'}, function(error, result) {
    if (result['info']['ocr']['adv_ocr']['status'] === 'complete') {
        let data = result['info']['ocr']['adv_ocr']['data'];
    }
});

Java:

Map result = cloudinary.uploader().upload("my_path", ObjectUtils.asMap("ocr","adv_ocr"));

Map info = (Map) ((Map)result.get("info")).get("ocr");
    if (((Map)info.get("adv_ocr")).get("status").equals("complete")) {
        ArrayList data = (ArrayList) ((Map)info.get("adv_ocr")).get("data");
    }

.NET:

dynamic result = JsonConvert.DeserializeObject(uploadResult);
if (result.info.ocr.adv_ocr.status.Value == "complete")
{
    var data = result.info.ocr.adv_ocr.data;
}

CLI:

cld uploader upload "black_car.jpeg" ocr="adv_ocr">result.json

Below are a few examples of ways to use the text extracted from an image:

1. Write the detected text to a file:

In the example below, the text extracted from the image is saved in the file system in an image_texts subfolder using the filename result_<public_id>.txt.

Ruby PHP Python Node.js Java .NET CLI All

Ruby:

if result['info']['ocr']['adv_ocr']['status'] == 'complete'
  data = result['info']['ocr']['adv_ocr']['data']
  texts = data.map{|blocks| 
    annotations = blocks['textAnnotations'] || []
    first_annotation = annotations.first || {}
    (first_annotation['description'] || '').strip
  }.compact.join("\n")
  File.open("image_texts/#{result['public_id']}.txt", 'w'){|f| f.write(texts)}
end

PHP (cloudinary_php v2.x):

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
    $texts = "";
    foreach($data as $blocks){
      $annotations = !empty($blocks["textAnnotations"]) ? $blocks["textAnnotations"] : [];
      $first_annotation = !empty($annotations[0]) ? $annotations[0] : [];
      $texts .= !empty($first_annotation["description"]) ? trim($first_annotation["description"])."\r\n" : "";
    }
    file_put_contents("image_texts/{$result['public_id']}.txt", $texts);
}

Library:

PHP (cloudinary_php v1.x (legacy)):

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
    $texts = "";
    foreach($data as $blocks){
      $annotations = !empty($blocks["textAnnotations"]) ? $blocks["textAnnotations"] : [];
      $first_annotation = !empty($annotations[0]) ? $annotations[0] : [];
      $texts .= !empty($first_annotation["description"]) ? trim($first_annotation["description"])."\r\n" : "";
    }
    file_put_contents("image_texts/{$result['public_id']}.txt", $texts);
}

Library:

Python:

if result['info']['ocr']['adv_ocr']['status'] == 'complete':
    data = result['info']['ocr']['adv_ocr']['data']
    texts = json.dumps(data, indent=4)
    f = open("image_texts/result_" + result['public_id'] + ".txt", "w")
    f.write(texts)
    f.close()

Node.js:

if (result['info']['ocr']['adv_ocr']['status'] === 'complete') {
    let data = result['info']['ocr']['adv_ocr']['data'];
    let texts = data.map(blocks => {
        let annotations = blocks['textAnnotations'] || [];
        let firstAnnotation = annotations[0] || {};
        return (firstAnnotation['description'] || '').trim();
    }).filter((obj) => obj).join('\n');
    fs.writeFile('image_texts/' + result['public_id'] + '.txt', texts, (err) => {
        if (err) throw err;
        console.log('Saved');
    });
}

Java:

Map info = (Map) ((Map)result.get("info")).get("ocr");
    if (((Map)info.get("adv_ocr")).get("status").equals("complete")) {
        ArrayList data = (ArrayList) ((Map)info.get("adv_ocr")).get("data");
        JSONArray texts = new JSONArray(data);
        try (FileWriter writer = new FileWriter("image_texts"+result.get("public_id") + ".txt")) {
            writer.write(String.valueOf(texts));
            writer.close();
        }
    }

.NET:

if(result.info.ocr.adv_ocr.status.Value == "complete")
{
    var data = result.info.ocr.adv_ocr.data;
    var texts = Convert.ToString(data);
    File.WriteAllText("image_texts/result_" + result.public_id + ".txt", texts);
}

CLI:

cld admin update "black_car.jpeg" ocr="adv_ocr">result.json

2. If an image has text, store it in a separate Cloudinary account folder

In the example below, the rename method is used to update the image IDs of images without text to a folder structure using the no_text folder, and changes the public ID's of images with text to an ID in the with_text folder.

Ruby PHP Python Node.js Java .NET CLI All

Ruby:

if result['info']['ocr']['adv_ocr']['status'] == 'complete'
  data = result['info']['ocr']['adv_ocr']['data']
  folder = data.all?{|i| i.empty?} ?  'no_text' : 'with_text'
  Cloudinary::Uploader.rename(
    result['public_id'], # from_public_id
    "#{folder}/#{result['public_id']}" # to_public_id
  )
end

PHP (cloudinary_php v2.x):

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
  $data = $result["info"]["ocr"]["adv_ocr"]["data"];
  $folder = "no_text";
  $folder = !empty(current($data)['textAnnotations']) ? "with_text" : "no_text";
  $uploader->rename(
    $result["public_id"], # from_public_id
    "{$folder}/{$result['public_id']}" # to_public_id
  );
}

Library:

PHP (cloudinary_php v1.x (legacy)):

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
  $data = $result["info"]["ocr"]["adv_ocr"]["data"];
  $folder = "no_text";
  $folder = !empty(current($data)['textAnnotations']) ? "with_text" : "no_text";
  \Cloudinary\Uploader::rename(
    $result["public_id"], # from_public_id
    "{$folder}/{$result['public_id']}" # to_public_id
  );
}

Library:

Python:

if result['info']['ocr']['adv_ocr']['status'] == 'complete':
    data = result['info']['ocr']['adv_ocr']['data']
    folder = 'with_text' if ("textAnnotations" in data) else 'no_text'
    cloudinary.uploader.rename(
        result['public_id'],                # from_public_id
        folder + "/" + result['public_id']  # to_public_id
    )

Node.js:

if (result['info']['ocr']['adv_ocr']['status'] === 'complete') {
    let data = result['info']['ocr']['adv_ocr']['data'];
    let folder = data.every(el => {return Object.keys(el).length === 0}) ? 'no_text' : 'with_text'; 
    cloudinary.v2.uploader.rename(
        result['public_id'], // from_public_id
        folder + '/' + result['public_id'] // to_public_id
    );
}

Java:

Map info = (Map) ((Map)result.get("info")).get("ocr");
    if (((Map)info.get("adv_ocr")).get("status").equals("complete")) {
        ArrayList data = (ArrayList) ((Map)info.get("adv_ocr")).get("data");
        String folder = "with_text";
        if (data.isEmpty() || data.get(0).equals(emptyMap())) {
            folder = "no_text";
        }
        String public_id = (String) result.get("public_id");
        Map res = cloudinary.uploader().rename(public_id, folder + "/"+ public_id,ObjectUtils.emptyMap());     
    }

.NET:

if(result.info.ocr.adv_ocr.status.Value == "complete")
{
    var data = result.info.ocr.adv_ocr.data;
    var folder = "with_text";
    if ((data.Count < 1) || (Convert.ToString(data.First) == "{}") || (String.IsNullOrEmpty(Convert.ToString(data.First))))
    {
        folder = "no_text";
    }
    var renameParams = new RenameParams(
        fromPublicId: data.public_id,               // from_public_id
        toPublicId: folder + "/" + data.public_id   // to_public_id
    );
    var renameResult = cloudinary.Rename(renameParams);
}

CLI:

cld uploader rename "black_car" "with_text/black_car"

3. Tag images with specific words if detected

For example, for each resume scanned into a career site, check whether the words "Cloudinary", "MBA", or "algorithm" appear. If so, tag the resume file with the relevant keywords.

Ruby PHP Python Node.js Java .NET CLI All

Ruby:

TAGS = %w(Cloudinary MBA algorithm).freeze
if result['info']['ocr']['adv_ocr']['status'] == 'complete'
  data = result['info']['ocr']['adv_ocr']['data']
  texts = data.map{|blocks| 
    annotations = blocks['textAnnotations'] || []
    first_annotation = annotations.first || {}
    (first_annotation['description'] || '').strip
  }.compact.join(" ")
  tags = TAGS.select{|tag| texts =~ /\b#{tag}\b/i}
  unless tags.empty?
    Cloudinary::Uploader.explicit(result['public_id'], type: 'upload', tags: tags)
  end
end

PHP (cloudinary_php v2.x):

define("TAGS", explode(" ", "Cloudinary MBA algorithm"));

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
    foreach($data as $blocks){
        $annotations = !empty($blocks["textAnnotations"]) ? $blocks["textAnnotations"] : [];
        $first_annotation = !empty($annotations[0]) ? $annotations[0] : [];
        $texts .= !empty($first_annotation["description"]) ? trim($first_annotation["description"])."\r\n" : "";
    }
    foreach(TAGS as $tag){
        if(strpos($texts, $tag) !== false){
            $tags[] = $tag;
        }   
    }
    if(!empty($tags)){
        $uploader->explicit($result["public_id"], ["type" => "upload", "tags" => $tags]);
    }
}

Library:

PHP (cloudinary_php v1.x (legacy)):

define("TAGS", explode(" ", "Cloudinary MBA algorithm"));

if($result["info"]["ocr"]["adv_ocr"]["status"] == "complete"){
    $data = $result["info"]["ocr"]["adv_ocr"]["data"];
    foreach($data as $blocks){
        $annotations = !empty($blocks["textAnnotations"]) ? $blocks["textAnnotations"] : [];
        $first_annotation = !empty($annotations[0]) ? $annotations[0] : [];
        $texts .= !empty($first_annotation["description"]) ? trim($first_annotation["description"])."\r\n" : "";
    }
    foreach(TAGS as $tag){
        if(strpos($texts, $tag) !== false){
            $tags[] = $tag;
        }   
    }
    if(!empty($tags)){
        \Cloudinary\Uploader::explicit($result["public_id"], ["type" => "upload", "tags" => $tags]);
    }
}

Library:

Python:

TAGS = ("Cloudinary MBA algorithm").split(" ") 
if result['info']['ocr']['adv_ocr']['status'] == 'complete': 
  data = result['info']['ocr']['adv_ocr']['data'] 
  texts = json.dumps(data, indent=4) 
  tags = [tag for tag in TAGS if tag.lower() in texts.lower()] 
  if (bool(tags) and bool(tags[0])): 
    cloudinary.uploader.explicit(result['public_id'], 
    type = "upload", 
    tags = tags)

Node.js:

const TAGS = ['Cloudinary', 'MBA', 'algorithm'];
if (result['info']['ocr']['adv_ocr']['status'] === 'complete') {
    let data = result['info']['ocr']['adv_ocr']['data'];
    let texts = data.map(blocks => {
        let annotations = blocks['textAnnotations'] || [];
        let firstAnnotation = annotations[0] || {};
        return (firstAnnotation['description'] || '').trim();
    }).filter((obj) => obj).join(' ');
    let tags = TAGS.filter(tag => {return texts.match(new RegExp(tag, 'i'))});
    if (tags.length > 0) {
        cloudinary.v2.uploader.explicit(result['public_id'], {type: 'upload', tags: tags});
    }
}

Java:

ArrayList <String> TAGS= new ArrayList();
TAGS.add("Cloudinary");
TAGS.add("MBA");
TAGS.add("algorithm")
Map info = (Map) ((Map)result.get("info")).get("ocr");

if (((Map)info.get("adv_ocr")).get("status").equals("complete")) {
    ArrayList data = (ArrayList) ((Map)info.get("adv_ocr")).get("data");
    JSONArray texts = new JSONArray(data);
    ArrayList tags = new ArrayList();

    for (String tag: TAGS) {
        if (texts.toString().toLowerCase().contains(tag.toLowerCase())){
          tags.add(tag);
        }
    }

    if (tags.size()>0){
        String public_id = (String) result.get("public_id");
        cloudinary.uploader().explicit(public_id, ObjectUtils.asMap("type", "upload", "tags", tags));
    }
}

.NET:

var TAGS = ("Cloudinary MBA algorithm").Split(" ").ToList();
if (result.info.ocr.adv_ocr.status.Value == "complete")
{
    var data = result.info.ocr.adv_ocr.data;
    var texts = Convert.ToString(data);
    var tags = new List<string>();
    foreach (var tag in TAGS)
    {
        if (texts.ToLower().Contains(tag.ToLower()))
            tags.Add(tag);
    }
    if (tags.Count > 0)
    {
        var explicitParams = new ExplicitParams("sample")
        {
            Type = "upload",
            PublicId = result.public_id,
            Tags = string.Join(",", tags.ToArray())
        };

        var explicitResult = cloudinary.Explicit(explicitParams);
    }                            
}

CLI:

cld uploader add_tag "Cloudinary, MBA, algorithm" '["black_car"]'

Blurring or pixelating detected text

Many images may have text, such as phone numbers, web site addresses, license plates, or other personal or commercial data, that you don't want visible in your delivered images. To blur or pixelate all detected text in an image, you can use Cloudinary's built-in pixelate_region or blur_region effect with the gravity parameter set to ocr_text. For example, we've blurred out the brand and model names on this smartphone:

Original

Blur branding texts

URL Ruby PHP Python Node.js Java JS jQuery React Vue.js Angular .NET iOS Android Kotlin All

URL:

https://res.cloudinary.com/demo/image/upload/e_blur_region:800,g_ocr_text/smartphone2.jpg

Ruby:

cl_image_tag("smartphone2.jpg", :effect=>"blur_region:800", :gravity=>"ocr_text")

PHP (cloudinary_php v2.x):

(new ImageTag('smartphone2.jpg'))
  ->effect(Effect::blur()->strength(800)
  ->region(
  Region::ocr())
  );

Library:

PHP (cloudinary_php v1.x (legacy)):

cl_image_tag("smartphone2.jpg", array("effect"=>"blur_region:800", "gravity"=>"ocr_text"))

Library:

Python:

CloudinaryImage("smartphone2.jpg").image(effect="blur_region:800", gravity="ocr_text")

Node.js:

cloudinary.image("smartphone2.jpg", {effect: "blur_region:800", gravity: "ocr_text"})

Java:

cloudinary.url().transformation(new Transformation().effect("blur_region:800").gravity("ocr_text")).imageTag("smartphone2.jpg");

JS (js-url-gen v1.x):

new CloudinaryImage("smartphone2.jpg").effect(
  blur()
    .strength(800)
    .region(ocr())
);

Library:

JS (cloudinary-core v2.x (legacy)):

cloudinary.imageTag('smartphone2.jpg', {effect: "blur_region:800", gravity: "ocr_text"}).toHtml();

Library:

jQuery:

$.cloudinary.image("smartphone2.jpg", {effect: "blur_region:800", gravity: "ocr_text"})

React:

<Image publicId="smartphone2.jpg" >
  <Transformation effect="blur_region:800" gravity="ocr_text" />
</Image>

Vue.js:

<cld-image public-id="smartphone2.jpg" >
  <cld-transformation effect="blur_region:800" gravity="ocr_text" />
</cld-image>

Angular:

<cl-image public-id="smartphone2.jpg" >
  <cl-transformation effect="blur_region:800" gravity="ocr_text">
  </cl-transformation>
</cl-image>

.NET:

cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("blur_region:800").Gravity("ocr_text")).BuildImageTag("smartphone2.jpg")

iOS:

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("blur_region:800").setGravity("ocr_text")).generate("smartphone2.jpg")!, cloudinary: cloudinary)

Android:

MediaManager.get().url().transformation(new Transformation().effect("blur_region:800").gravity("ocr_text")).generate("smartphone2.jpg");

Kotlin:

// This code example is not currently available.

Tip

When blurring or pixelating to hide content, you may want to take advantage of one of the access control options to prevent users from accessing the non-blurred or non-pixelated versions of the image.

Overlaying detected text with images

Overlaying an image based on OCR text detection is similar to the process for overlaying images in other scenarios: you specify the image to overlay, the width of the overlay, and the gravity (location) for the overlay. When you specify ocr_text as the gravity, each detected text element is automatically covered with the specified image.

In most cases, it works best to specify a relative width instead of an absolute width for the overlay. The relative width adjusts the size of the overlay image relative to the size of the detected text element. To do this, just add the fl_region_relative flag to your transformation, and specify the width of the overlay image as a percentage (1.0 = 100%) of the text element.

For example, suppose you run a real estate website where individuals or companies can list homes for sale. For revenue recognition purposes, it's important that the listings do not display private phone numbers or those of other real estate organizations. So instead, you overlay an image with your site's contact information that covers any detected text in the uploaded images.

URL Ruby PHP Python Node.js Java JS jQuery React Vue.js Angular .NET iOS Android Kotlin All

URL:

https://res.cloudinary.com/demo/image/upload/l_call_text/c_scale,fl_region_relative,w_1.1/fl_layer_apply,g_ocr_text/home_4_sale.jpg

Ruby:

cl_image_tag("home_4_sale.jpg", :transformation=>[
  {:overlay=>"call_text"},
  {:flags=>"region_relative", :width=>1.1, :crop=>"scale"},
  {:flags=>"layer_apply", :gravity=>"ocr_text"}
  ])

PHP (cloudinary_php v2.x):

(new ImageTag('home_4_sale.jpg'))
  ->overlay(Overlay::source(
  Source::image("call_text")
  ->transformation((new Transformation())
  ->resize(Resize::scale()->width(1.1)
  ->regionRelative()
  ))
  )
  ->position((new Position())
  ->gravity(
  Gravity::focusOn(
  FocusOn::ocr()))
  )
  );

Library:

PHP (cloudinary_php v1.x (legacy)):

cl_image_tag("home_4_sale.jpg", array("transformation"=>array(
  array("overlay"=>"call_text"),
  array("flags"=>"region_relative", "width"=>"1.1", "crop"=>"scale"),
  array("flags"=>"layer_apply", "gravity"=>"ocr_text")
  )))

Library:

Python:

CloudinaryImage("home_4_sale.jpg").image(transformation=[
  {'overlay': "call_text"},
  {'flags': "region_relative", 'width': "1.1", 'crop': "scale"},
  {'flags': "layer_apply", 'gravity': "ocr_text"}
  ])

Node.js:

cloudinary.image("home_4_sale.jpg", {transformation: [
  {overlay: "call_text"},
  {flags: "region_relative", width: "1.1", crop: "scale"},
  {flags: "layer_apply", gravity: "ocr_text"}
  ]})

Java:

cloudinary.url().transformation(new Transformation()
  .overlay(new Layer().publicId("call_text")).chain()
  .flags("region_relative").width(1.1).crop("scale").chain()
  .flags("layer_apply").gravity("ocr_text")).imageTag("home_4_sale.jpg");

JS (js-url-gen v1.x):

new CloudinaryImage("home_4_sale.jpg").overlay(
  source(
    image("call_text").transformation(
      new MediaTransformation().resize(scale().width(1.1).regionRelative())
    )
  ).position(new Position().gravity(focusOn(ocr())))
);

Library:

JS (cloudinary-core v2.x (legacy)):

cloudinary.imageTag('home_4_sale.jpg', {transformation: [
  {overlay: new cloudinary.Layer().publicId("call_text")},
  {flags: "region_relative", width: "1.1", crop: "scale"},
  {flags: "layer_apply", gravity: "ocr_text"}
  ]}).toHtml();

Library:

jQuery:

$.cloudinary.image("home_4_sale.jpg", {transformation: [
  {overlay: new cloudinary.Layer().publicId("call_text")},
  {flags: "region_relative", width: "1.1", crop: "scale"},
  {flags: "layer_apply", gravity: "ocr_text"}
  ]})

React:

<Image publicId="home_4_sale.jpg" >
  <Transformation overlay="call_text" />
  <Transformation flags="region_relative" width="1.1" crop="scale" />
  <Transformation flags="layer_apply" gravity="ocr_text" />
</Image>

Vue.js:

<cld-image public-id="home_4_sale.jpg" >
  <cld-transformation :overlay="call_text" />
  <cld-transformation flags="region_relative" width="1.1" crop="scale" />
  <cld-transformation flags="layer_apply" gravity="ocr_text" />
</cld-image>

Angular:

<cl-image public-id="home_4_sale.jpg" >
  <cl-transformation overlay="call_text">
  </cl-transformation>
  <cl-transformation flags="region_relative" width="1.1" crop="scale">
  </cl-transformation>
  <cl-transformation flags="layer_apply" gravity="ocr_text">
  </cl-transformation>
</cl-image>

.NET:

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Overlay(new Layer().PublicId("call_text")).Chain()
  .Flags("region_relative").Width(1.1).Crop("scale").Chain()
  .Flags("layer_apply").Gravity("ocr_text")).BuildImageTag("home_4_sale.jpg")

iOS:

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setOverlay("call_text").chain()
  .setFlags("region_relative").setWidth(1.1).setCrop("scale").chain()
  .setFlags("layer_apply").setGravity("ocr_text")).generate("home_4_sale.jpg")!, cloudinary: cloudinary)

Android:

MediaManager.get().url().transformation(new Transformation()
  .overlay(new Layer().publicId("call_text")).chain()
  .flags("region_relative").width(1.1).crop("scale").chain()
  .flags("layer_apply").gravity("ocr_text")).generate("home_4_sale.jpg");

Kotlin:

// This code example is not currently available.

Original sign

Sign with your text overlay

Text-based cropping

When you want to be sure that text in an image is retained during a crop transformation, you can specify ocr_text as the gravity (g_ocr_text in URLs).

For example, the following example demonstrates what happens to the itsSnacktime.com text in the picture below if you crop it to a square with default (center gravity) cropping, auto gravity cropping, or ocr_text gravity cropping:

Original

default gravity
(centered)

auto gravity
(focus on most prominent elements)

ocr_text gravity
(focus on text regions)

The transformation code for the last image looks like this:

URL Ruby PHP Python Node.js Java JS jQuery React Vue.js Angular .NET iOS Android Kotlin All

URL:

https://res.cloudinary.com/demo/image/upload/c_fill,g_ocr_text,h_250,w_250/snacktime.jpg

Ruby:

cl_image_tag("snacktime.jpg", :gravity=>"ocr_text", :height=>250, :width=>250, :crop=>"fill")

PHP (cloudinary_php v2.x):

(new ImageTag('snacktime.jpg'))
  ->resize(Resize::fill()->width(250)
->height(250)
  ->gravity(
  Gravity::focusOn(
  FocusOn::ocr()))
  );

Library:

PHP (cloudinary_php v1.x (legacy)):

cl_image_tag("snacktime.jpg", array("gravity"=>"ocr_text", "height"=>250, "width"=>250, "crop"=>"fill"))

Library:

Python:

CloudinaryImage("snacktime.jpg").image(gravity="ocr_text", height=250, width=250, crop="fill")

Node.js:

cloudinary.image("snacktime.jpg", {gravity: "ocr_text", height: 250, width: 250, crop: "fill"})

Java:

cloudinary.url().transformation(new Transformation().gravity("ocr_text").height(250).width(250).crop("fill")).imageTag("snacktime.jpg");

JS (js-url-gen v1.x):

new CloudinaryImage("snacktime.jpg").resize(
  fill()
    .width(250)
    .height(250)
    .gravity(focusOn(ocr()))
);

Library:

JS (cloudinary-core v2.x (legacy)):

cloudinary.imageTag('snacktime.jpg', {gravity: "ocr_text", height: 250, width: 250, crop: "fill"}).toHtml();

Library:

jQuery:

$.cloudinary.image("snacktime.jpg", {gravity: "ocr_text", height: 250, width: 250, crop: "fill"})

React:

<Image publicId="snacktime.jpg" >
  <Transformation gravity="ocr_text" height="250" width="250" crop="fill" />
</Image>

Vue.js:

<cld-image public-id="snacktime.jpg" >
  <cld-transformation gravity="ocr_text" height="250" width="250" crop="fill" />
</cld-image>

Angular:

<cl-image public-id="snacktime.jpg" >
  <cl-transformation gravity="ocr_text" height="250" width="250" crop="fill">
  </cl-transformation>
</cl-image>

.NET:

cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("ocr_text").Height(250).Width(250).Crop("fill")).BuildImageTag("snacktime.jpg")

iOS:

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("ocr_text").setHeight(250).setWidth(250).setCrop("fill")).generate("snacktime.jpg")!, cloudinary: cloudinary)

Android:

MediaManager.get().url().transformation(new Transformation().gravity("ocr_text").height(250).width(250).crop("fill")).generate("snacktime.jpg");

Kotlin:

// This code example is not currently available.

Alternatively, in cases where text is only one consideration of cropping priority, you can set the gravity parameter to auto with the ocr_text option (g_auto:ocr_text in URLs), which gives a higher priority to detected text, but also gives priority to faces and other very prominent elements of an image.

Avoiding text

To minimize the likelihood of having text in a cropped image, set the gravity parameter to auto with the ocr_text_avoid option (g_auto:ocr_text_avoid in URLs).

For example, in the photo below, you may not want to show the name of the flower shop.

Using g_auto by itself makes the shop front the focal point, but if we use g_auto:ocr_text_avoid, the side of the photo without the text is shown.

URL Ruby PHP Python Node.js Java JS jQuery React Vue.js Angular .NET iOS Android Kotlin All

URL:

https://res.cloudinary.com/demo/image/upload/ar_0.8,c_fill,g_auto:ocr_text_avoid,h_400/docs/flower_shop.jpg

Ruby:

cl_image_tag("docs/flower_shop.jpg", :aspect_ratio=>"0.8", :gravity=>"auto:ocr_text_avoid", :height=>400, :crop=>"fill")

PHP (cloudinary_php v2.x):

(new ImageTag('docs/flower_shop.jpg'))
  ->resize(Resize::fill()->height(400)
->aspectRatio(0.8)
  ->gravity(
  Gravity::autoGravity()
  ->autoFocus(
  AutoFocus::focusOn(
  FocusOn::ocr())->avoid())
  )
  );

Library:

PHP (cloudinary_php v1.x (legacy)):

cl_image_tag("docs/flower_shop.jpg", array("aspect_ratio"=>"0.8", "gravity"=>"auto:ocr_text_avoid", "height"=>400, "crop"=>"fill"))

Library:

Python:

CloudinaryImage("docs/flower_shop.jpg").image(aspect_ratio="0.8", gravity="auto:ocr_text_avoid", height=400, crop="fill")

Node.js:

cloudinary.image("docs/flower_shop.jpg", {aspect_ratio: "0.8", gravity: "auto:ocr_text_avoid", height: 400, crop: "fill"})

Java:

cloudinary.url().transformation(new Transformation().aspectRatio("0.8").gravity("auto:ocr_text_avoid").height(400).crop("fill")).imageTag("docs/flower_shop.jpg");

JS (js-url-gen v1.x):

new CloudinaryImage("docs/flower_shop.jpg").resize(
  fill()
    .height(400)
    .aspectRatio(0.8)
    .gravity(autoGravity().autoFocus(focusOn(ocr()).avoid()))
);

Library:

JS (cloudinary-core v2.x (legacy)):

cloudinary.imageTag('docs/flower_shop.jpg', {aspectRatio: "0.8", gravity: "auto:ocr_text_avoid", height: 400, crop: "fill"}).toHtml();

Library:

jQuery:

$.cloudinary.image("docs/flower_shop.jpg", {aspect_ratio: "0.8", gravity: "auto:ocr_text_avoid", height: 400, crop: "fill"})

React:

<Image publicId="docs/flower_shop.jpg" >
  <Transformation aspectRatio="0.8" gravity="auto:ocr_text_avoid" height="400" crop="fill" />
</Image>

Vue.js:

<cld-image public-id="docs/flower_shop.jpg" >
  <cld-transformation aspect-ratio="0.8" gravity="auto:ocr_text_avoid" height="400" crop="fill" />
</cld-image>

Angular:

<cl-image public-id="docs/flower_shop.jpg" >
  <cl-transformation aspect-ratio="0.8" gravity="auto:ocr_text_avoid" height="400" crop="fill">
  </cl-transformation>
</cl-image>

.NET:

cloudinary.Api.UrlImgUp.Transform(new Transformation().AspectRatio("0.8").Gravity("auto:ocr_text_avoid").Height(400).Crop("fill")).BuildImageTag("docs/flower_shop.jpg")

iOS:

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setAspectRatio("0.8").setGravity("auto:ocr_text_avoid").setHeight(400).setCrop("fill")).generate("docs/flower_shop.jpg")!, cloudinary: cloudinary)

Android:

MediaManager.get().url().transformation(new Transformation().aspectRatio("0.8").gravity("auto:ocr_text_avoid").height(400).crop("fill")).generate("docs/flower_shop.jpg");

Kotlin:

// This code example is not currently available.

g_auto

g_auto:ocr_text_avoid

Signed URLs

Cloudinary's dynamic image transformation URLs are powerful tools for agile web and mobile development. However, due to the potential costs of your customers accessing unplanned dynamic URLs that apply the OCR text detection or extraction functionality, image transformation add-on URLs are required (by default) to be signed using Cloudinary's authenticated API or, alternatively, you can eagerly generate the requested derived images using Cloudinary's authenticated API.

To create a signed Cloudinary URL, set the sign_url parameter to true when building a URL or creating an image tag.

For example, to generate a signed URL when applying a blur effect on the text of an image:

Ruby PHP Python Node.js Java JS jQuery React Vue.js Angular .NET iOS Android Kotlin All

Ruby:

cl_image_tag("smartphone2.jpg", :effect=>"blur_region:800", :gravity=>"ocr_text", :sign_url=>true)

PHP (cloudinary_php v2.x):

(new ImageTag('smartphone2.jpg'))
  ->effect(Effect::blur()->strength(800)
  ->region(
  Region::ocr())
  )
  ->sign();

Library:

PHP (cloudinary_php v1.x (legacy)):

cl_image_tag("smartphone2.jpg", array("effect"=>"blur_region:800", "gravity"=>"ocr_text", "sign_url"=>true))

Library:

Python:

CloudinaryImage("smartphone2.jpg").image(effect="blur_region:800", gravity="ocr_text", sign_url=True)

Node.js:

cloudinary.image("smartphone2.jpg", {effect: "blur_region:800", gravity: "ocr_text", sign_url: true})

Java:

cloudinary.url().transformation(new Transformation().effect("blur_region:800").gravity("ocr_text")).signed(true).imageTag("smartphone2.jpg");

JS (js-url-gen v1.x):

new CloudinaryImage("smartphone2.jpg")
  .effect(
    blur()
      .strength(800)
      .region(ocr())
  )
  .setSignature("BDoTEjNU");

Library:

JS (cloudinary-core v2.x (legacy)):

cloudinary.imageTag('smartphone2.jpg', {effect: "blur_region:800", gravity: "ocr_text", signUrl: true}).toHtml();

Library:

jQuery:

$.cloudinary.image("smartphone2.jpg", {effect: "blur_region:800", gravity: "ocr_text"})

React:

<Image publicId="smartphone2.jpg" signUrl="true">
  <Transformation effect="blur_region:800" gravity="ocr_text" />
</Image>

Vue.js:

<cld-image public-id="smartphone2.jpg" sign-url="true">
  <cld-transformation effect="blur_region:800" gravity="ocr_text" />
</cld-image>

Angular:

<cl-image public-id="smartphone2.jpg" sign-url="true">
  <cl-transformation effect="blur_region:800" gravity="ocr_text">
  </cl-transformation>
</cl-image>

.NET:

cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("blur_region:800").Gravity("ocr_text")).Signed(true).BuildImageTag("smartphone2.jpg")

iOS:

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("blur_region:800").setGravity("ocr_text")).generate("smartphone2.jpg", signUrl: true)!, cloudinary: cloudinary)

Android:

MediaManager.get().url().transformation(new Transformation().effect("blur_region:800").gravity("ocr_text")).signed(true).generate("smartphone2.jpg");

Kotlin:

// This code example is not currently available.

The generated Cloudinary URL shown below includes a signature component (/s--BDoTEjNU--/). Only URLs with a valid signature that matches the requested image transformation will be approved for on-the-fly image transformation and delivery.

https://res.cloudinary.com/demo/image/upload/s--BDoTEjNU--/e_blur_region:800,g_ocr_text/smartphone2.jpg

For more details on signed URLs, see Signed delivery URLs.

Notes

You can optionally remove the signed URL default requirement for a particular add-on by selecting it in the Allow unsigned add-on transformations section of the Security account settings in the Cloudinary console.
No OCR mechanism can identify 100% of the text in all images. The results may be affected by things like font, color, contrast between text and background, text angle, and more.
The OCR engine requires images with a minimum resolution of 1024 X 768.

Language support

By default, the add-on supports latin languages. You can instruct the add-on to perform the text detection in a non-latin language by adding the 2-letter language code to the adv_ocr value, separated by a colon. For example, if you expect your image to include Russian characters, set the value to adv_ocr:ru. Note that when you include a language code, the structure and breakdown of the response is different than without. The full list of supported languages and their language codes can be found here.

✔️ Feedback sent!

✖️

Error

Unfortunately there's been an error sending your feedback.

Rate this page: