AtixReader

AtixReader es un componente para la visualización de archivos PDF y la integración de herramientas de OCR (Reconocimiento Óptico de Caracteres) en React. Esta librería cuenta con diversas funcionalidades que permiten una lectura más ágil y una mejor interacción con los documentos PDF.

Demo atix-reader-demo

Instalación

Antes de comenzar a utilizar la librería, es importante asegurarse de tener instalado React en su versión 18 o superior. Una vez cumplido este requisito, puede proceder con la instalación de la librería Atix Reader.

Para instalar Atix Reader, siga los siguientes pasos según su gestor de paquetes:

NPM

Ejecute el siguiente comando en su terminal: npm install atix-reader

Yarn

Ejecute el siguiente comando en su terminal:

yarn add atix-reader

Con estos comandos, se instalará la librería Atix Reader en su proyecto y estará lista para ser utilizada.

Uso básico

Una vez que ha instalado la librería Atix Reader en su proyecto, puede importar el componente principal AtixReader y comenzar a utilizarlo en su aplicación de React.

Para importar AtixReader, utilice la siguiente sintaxis:

import { AtixReader } from 'atix-reader'

Luego, agrega el componente a tu código JSX y configura las siguientes propiedades:

• pdfSrc: (string) El enlace URL o el archivo local del documento PDF a mostrar en el lector.
• initialScale: (number) El nivel de escala inicial para mostrar el documento. Por defecto es 1. Valores menores de 1 reducen el tamaño y valores mayores lo aumentan.
• onDocumentLoad: (func) Una función de devolución de llamada que se ejecuta después de cargar el documento. Recibe un objeto con información sobre el documento cargado, como el número de páginas.
• showBaseTools: (bool) Activa la barra de herramientas base del lector, que incluye las herramientas de zoom y paneo y el divisor de páginas. Por defecto es true.
• showThumbnails: (bool) Muestra un panel lateral que contiene miniaturas de cada página y permite navegar haciendo clic sobre ellas. Por defecto es true.
• showUploadFile: (bool) Permite cargar archivos locales y visualizarlos en el lector. Por defecto es false.

import { AtixReader } from 'atix-reader'

const App = () => {
  return (
    <AtixReader
      pdfSrc="https://example.com/example.pdf"
      initialScale={1.5}
      showBaseTools={true}
      showThumbnails={true}
      onDocumentLoad={(pdf) => console.log(pdf)}
    />
  )
}

En este ejemplo, se carga un archivo PDF desde una URL, se establece un nivel de escala inicial del 150% y se activan tanto la barra de herramientas base como el panel de miniaturas. Además, se establece una función de devolución de llamada para informar cuando se carga el documento y se imprime información sobre él en la consola.

Propiedades

El componente AtixReader acepta varias propiedades que se pueden utilizar para personalizar su apariencia y comportamiento en su aplicación. A continuación, se describen algunas de las propiedades más comunes que puede utilizar:

showBaseTools

Este prop activa la barra de herramientas base del lector, que incluye herramientas de zoom y paneo, así como un divisor de PDF. Si no se incluye este prop en el componente, la barra se ocultará.

<AtixReader showBaseTools={true} />

showThumbnails

Este prop muestra un panel lateral que contiene miniaturas de cada página del PDF y permite navegar haciendo clic en ellas.

<AtixReader showThumbnails={true} />

showUploadFile

Este prop activa una herramienta para subir archivos y visualizarlos localmente.

<AtixReader showUploadFile={true} />

Herramientas para OCR (Optical Character Recognition)

AtixReader permite el reconocimiento óptico de caracteres para archivos con contenido escaneado. La librería integra Tesseract.js para documentos con alta legibilidad, por lo que no es necesario un servicio externo. Sin embargo, también admite APIs de servicios externos, como Amazon Textract.

Para activar las herramientas de OCR, utilice el prop showOcrTools. Si no se utiliza este prop, las herramientas de OCR no se mostrarán.

<AtixReader showOcrTools={true} />

Para conectarse con Amazon Textract, es necesario proporcionar el enlace o link de la API, que debe recibir el archivo como path. Para ello, utilice el prop ocrApiUrl.

<AtixReader
  showOcrTools={true}
  ocrApiUrl="https://mytextractapi.com/api/extract"
/>

Tenga en cuenta que si no se proporciona un valor para ocrApiUrl, se utilizará la API integrada con Tesseract.js.

nodeSelector

AtixReader permite la selección de los nodos que son producidos por la lectura. La lectura se proyecta por palabras y los nodos se posicionaran automáticamente cuando la lectura sea finalizada y se cargue la página.

Para activar el selector se debe utilizar la propiedad enableOcrNodeSelector. Luego, al momento de realizar la selección del nodo, se emite un evento llamado onNodeSelection que devuelve un objeto dataSelected.

Este objeto contiene la siguiente información detallada sobre la selección del nodo:

• width: la anchura en píxeles del nodo seleccionado.
• height: la altura en píxeles del nodo seleccionado.
• xPos: la posición horizontal en píxeles del nodo seleccionado con respecto al borde izquierdo del documento.
• yPos: la posición vertical en píxeles del nodo seleccionado con respecto al borde superior del documento.
• sentence: la oración completa a la que pertenece el nodo seleccionado.
• nodes: un array de nodos HTML que representan las palabras individuales del nodo seleccionado. Cada elemento en el array es un nodo HTML que se puede usar para interactuar con la selección de una manera más detallada.

Estos datos pueden ser utilizados para implementar características como la resaltación de texto, la traducción de texto o cualquier otra característica que requiera información detallada sobre la selección del texto.

Un ejemplo del objeto emitido:

dataSelected = {
  width: '100px', // Ancho del nodo seleccionado
  height: '100px', // Alto del nodo seleccionado
  xPos: '23px', // Posición horizontal del nodo seleccionado
  yPos: '143px', // Posición vertical del nodo seleccionado
  sentence: 'Hola soy la frase seleccionada', // Texto seleccionado
  nodes: [
    HTMLElement, // Array de elementos HTML que corresponden al nodo seleccionado
    HTMLElement,
  ],
}

Ejemplo de uso:

import AtixReader from 'atix-reader'

const App = () => {
  const handleNodeSelection = (dataSelected) => {
    console.log(dataSelected)
  }

  return (
    <AtixReader
      pdfSrc="https://example.com/example.pdf"
      initialScale={1}
      ocrApiUrl="https://myocrapi.com/api/readpdf"
      showBaseTools
      showThumbnails
      showUploadFile
      onDocumentLoad={(pdf) => console.log(pdf)}
      enableOcrNodeSelector
      onNodeSelection={handleNodeSelection}
    />
  )
}

Notas sobre la API Tesseract

Si no se proporciona una URL para la API externa de OCR, AtixReader utilizará Tesseract para realizar el reconocimiento de caracteres. Sin embargo, hay algunas limitaciones que se deben tener en cuenta:

• La lectura con Tesseract es un poco más lenta que la del servicio externo, ya que ocurre en el cliente y utiliza los recursos computacionales de este. Por lo tanto, la velocidad de procesamiento dependerá de las condiciones del cliente.
• La lectura se realiza por página, cada vez que se carga una página. Actualmente, no se admite la lectura total del documento.
• Tesseract es recomendable solo para documentos con escaneos o imágenes legibles en blanco y negro y sin sombras. En la actualidad, no se admite el procesamiento ni la optimización de las imágenes.

Es importante tener en cuenta estas limitaciones antes de utilizar la opción predeterminada de Tesseract en AtixReader.

Aquí tienes la versión en español de la documentación proporcionada:

Extracciones de Texto OCR Externas

Esta sección proporciona información detallada sobre cómo manejar las extracciones de texto OCR utilizando el componente AtixReader, centrándose específicamente en la propiedad PolyTool y su interacción con la API OCR de Google.

Visión General

El componente AtixReader incluye una característica llamada PolyTool, que permite a los usuarios seleccionar áreas poligonales para la extracción de texto. Esta funcionalidad es particularmente útil cuando se trabaja con la API OCR de Google. La propiedad PolyTool habilita el modo de selección de polígonos y desencadena un evento al seleccionar, devolviendo los datos del polígono seleccionado.

Interfaz de PolyTool

La interfaz PolyTool se define de la siguiente manera:

interface PolyTool {
  enablePolySelection: boolean
  onPolySelected: (data: Poly) => void
}

• enablePolySelection: Un valor booleano que activa el modo de selección de polígonos.
• onPolySelected: Un manejador de eventos que recibe los datos del polígono seleccionado (Poly) al realizar la selección.

Estructura de Datos de Poly

La estructura de datos Poly representa el polígono seleccionado y está compuesta por datos de vértices, alineándose con las especificaciones de la API OCR de Google.

interface Vertex {
  x: number
  y: number
}

interface Poly {
  vertices: Vertex[]
  first: Vertex
  last: Vertex
}

Esta estructura facilita el envío de las coordenadas de la selección rectangular realizada por el usuario en la página del documento, permitiendo la comunicación con la API OCR.

Integración con Datos OCR Externos

El PolyTool se puede combinar con la propiedad ExternalOcrData de AtixReader para una funcionalidad mejorada.

Interfaz de ExternalOcrData

La interfaz ExternalOcrData se estructura de la siguiente manera:

interface WordsDataI {
  text: string
  vertices: Vertex[]
}

interface ExternalOcrDataI {
  textInPage?: WordsDataI[]
  table?: {
    boundingPoly: Poly
    lines: Lines
  }
}

Para simplificar, nos centraremos en la propiedad textInPage, que contiene un array de WordsDataI. Cada elemento en este array representa una palabra extraída por el proceso OCR, incluyendo su contenido de texto y los vértices que definen su posición.

Ejemplo de Datos OCR

Aquí hay un ejemplo de la respuesta JSON de la API OCR de Google, que ilustra la estructura de los datos recibidos:

{
  "pages": [
    {
      "height": 792,
      "width": 612,
      "confidence": 1.0,
      "text": "A Simple PDF File...",
      "words": [
        {
          "text": "A",
          "confidence": 0.9771065,
          "boundingPoly": {
            "vertices": [
              { "x": 0.10294118, "y": 0.06439394 },
              { "x": 0.13562092, "y": 0.06313131 },
              { "x": 0.13562092, "y": 0.09090909 },
              { "x": 0.104575165, "y": 0.09090909 }
            ]
          },
          "breakType": "SPACE"
        }
      ]
    }
  ]
}

AtixPdf procesa estos datos extrayendo los arrays text y vertices del boundingPoly de cada palabra en el array words. Los desarrolladores necesitan implementar lógica para manejar estos datos, especialmente al navegar entre diferentes páginas del documento.

Ejemplos Útiles de Implementación de ExternalOcrData

Esta sección proporciona ejemplos prácticos de cómo implementar la propiedad ExternalOcrData en el componente AtixReader. Estos ejemplos demuestran cómo obtener datos OCR de manera asíncrona e integrarlos en el componente.

Ejemplo 1: Usando React Hooks

En una aplicación estándar de React, puedes usar los hooks useEffect y useState para obtener datos OCR de manera asíncrona y pasarlos al componente AtixReader.

import React, { useState, useEffect } from 'react'
import AtixReader from 'atix-reader' // Ajusta la ruta de importación según sea necesario

const MyComponent = () => {
  const [ocrData, setOcrData] = useState(null)

  useEffect(() => {
    const fetchOcrData = async () => {
      try {
        const response = await fetch(
          'https://google.extract.ocr/example1/json1',
        )
        const data = await response.json()

        // Procesa los datos para ajustarse a la estructura de ExternalOcrDataI
        const textInPages = data.pages[0].words.map((word) => ({
          text: word.text,
          vertices: word.boundingPoly.vertices.map((vertex) => ({
            x: vertex.x,
            y: vertex.y,
          })),
        }))

        setOcrData({ textInPages })
      } catch (error) {
        console.error('Error al obtener datos OCR:', error)
      }
    }

    fetchOcrData()
  }, [])

  return <AtixReader externalOcrData={ocrData} />
}

export default MyComponent

Ejemplo 2: Usando getServerSideProps de Next.js

En una aplicación de Next.js, puedes usar getServerSideProps para obtener datos OCR en el lado del servidor y pasarlos como props al componente de la página.

import React from 'react'
import AtixReader from 'atix-reader' // Ajusta la ruta de importación según sea necesario

const HomePage = ({ ocrData }) => {
  return <AtixReader externalOcrData={ocrData} />
}

export async function getServerSideProps() {
  try {
    const response = await fetch(
      'https://google.extract.ocr/example1/json1',
    )
    const data = await response.json()

    // Procesa los datos para ajustarse a la estructura de ExternalOcrDataI
    const textInPages = data.pages[0].words.map((word) => ({
      text: word.text,
      vertices: word.boundingPoly.vertices.map((vertex) => ({
        x: vertex.x,
        y: vertex.y,
      })),
    }))

    return {
      props: {
        ocrData: { textInPages },
      },
    }
  } catch (error) {
    console.error('Error al obtener datos OCR:', error)
    return {
      props: {
        ocrData: { textInPages: [] },
      },
    }
  }
}

export default HomePage

Explicación

1. Gestión de Estado y Obtención de Datos: En el ejemplo de React, se utilizan los hooks useState y useEffect para gestionar el estado y obtener los datos OCR de manera asíncrona. En el ejemplo de Next.js, se utiliza getServerSideProps para obtener los datos en el lado del servidor.
2. Procesamiento de Datos: Los datos obtenidos se procesan para ajustarse a la estructura de ExternalOcrDataI, específicamente la propiedad textInPages.
3. Pasar Datos al Componente: Los datos procesados se pasan al componente AtixReader a través de la prop externalOcrData.

Estos ejemplos simplificados se centran únicamente en la prop externalOcrData, ignorando todas las demás props para mayor claridad. Este enfoque ayuda a entender cómo integrar la propiedad ExternalOcrData en diferentes entornos de React y Next.js.

Extracciones de Tablas OCR Externas

El componente AtixReader incluye un editor de tablas para interactuar con las extracciones de tablas de la API OCR de Google.

Habilitar el Editor de Tablas

Para habilitar el editor de tablas, necesitas usar el PolyTool (explicado en la sección de extracciones de texto) en combinación con la prop tableMode. Esta configuración permite habilitar el editor y usar un evento para devolver los datos de la tabla actualizados. Además, se utiliza la prop externalOcrData.table para pasar los datos de respuesta de la API OCR al componente.

Prop tableMode

• Propósito: Habilita el editor de tablas.
• Uso: Establece enable: true para activar el editor y usa el evento onTableSelected para capturar los datos de la tabla.

Prop externalOcrData.table

• Propósito: Pasa los datos de respuesta de la API OCR al componente.
• Uso: Proporciona los vértices de boundingPoly directamente en boundingPolyVertices y las líneas horizontales y verticales en el objeto lines.

Definición de la Interfaz

interface ExternalOcrDataI {
  textInPages?: WordsDataI[]
  table?: {
    boundingPolyVertices: Vertex[]
    lines: Lines
  }
}

Ejemplo de Datos OCR de la API de Google

export const dataMock = {
  boundingPoly: {
    vertices: [
      { x: 0.12962963, y: 0.17087542 },
      { x: 0.8703704, y: 0.17087542 },
      { x: 0.8703704, y: 0.36784512 },
      { x: 0.12962963, y: 0.36784512 }
    ],
    first: { x: 0.12962963, y: 0.17087542 },
    last: { x: 0.12962963, y: 0.36784512 }
  },
  verticalLines: [
    {
      vertices: [
        { x: 0.12962963, y: 0.17087542 },
        { x: 0.12962963, y: 0.36784512 }
      ],
      first: { x: 0.12962963, y: 0.17087542 },
      last: { x: 0.12962963, y: 0.36784512 }
    }
  ],
  horizontalLines: [
    {
      vertices: [
        { x: 0.13176471, y: 0.2935112 },
        { x: 0.8682353, y: 0.2935112 }
      ],
      first: { x: 0.13176471, y: 0.2935112 },
      last: { x: 0.8682353, y: 0.2935112 }
    }
  ]
};

Uso del boundingPoly y las Líneas

Para el boundingPoly, solo se necesitan los boundingPolyVertices. Los objetos completos para las líneas verticales y horizontales se pueden pasar tal como están.

Funcionalidad del Modo Tabla

Cuando tableMode.enable se establece en true, el visor de PDF renderiza la tabla en la posición especificada. Permite editar la posición de cada línea, agregar nuevas líneas, eliminar líneas e incluye funcionalidad de deshacer y rehacer mapeada a Ctrl+Z (deshacer) y Ctrl+Y (rehacer).

Es responsabilidad del desarrollador habilitar y deshabilitar este modo según sea necesario para crear la experiencia de usuario deseada para los propósitos de OCR de documentos.

Ejemplo de Uso

<AtixReader
  //...props
  tableMode={{
    enable: true,
    onTableSelected: (data) => {
      console.log('table data', data)
    },
  }}
  externalOcrData={{
    table: {
      boundingPolyVertices: tableData.boundingPoly.vertices,
      lines: {
        verticalLines: tableData.verticalLines,
        horizontalLines: tableData.horizontalLines,
      },
    },
  }}
/>

Este ejemplo muestra cómo pasar los datos de la tabla OCR al componente AtixReader utilizando la prop externalOcrData.table. Asegúrate de que los datos de la tabla se ajusten a la estructura esperada para que el editor de tablas funcione correctamente.

Conclusión

El componente AtixReader proporciona una potente herramienta para manejar extracciones de texto y tablas OCR utilizando la API OCR de Google. La integración de la propiedad PolyTool permite una selección precisa de áreas poligonales, mientras que la propiedad ExternalOcrData facilita la incorporación de datos OCR externos en el componente. Los ejemplos proporcionados demuestran cómo implementar estas funcionalidades en aplicaciones React y Next.js, permitiendo a los desarrolladores crear experiencias de usuario avanzadas para la manipulación de documentos OCR.