How danielbmancini/cansa-vision works
1. What this repository does
- Cansa-Vision is a document-processing pipeline for handwritten time cards (“cartões-ponto”).
- It turns scanned images or photos of point cards into structured time entries and then writes those entries into an Excel template.
2. Overall architecture
- The repo is a small, script-driven pipeline rather than an application server.
- The flow is: input image/document → OCR extraction → text normalization/interpretation → spreadsheet population.
- There are two AI services in the chain:
- Azure Computer Vision for OCR.
- Vertex AI / gcloud for higher-level interpretation of the raw OCR output.
3. Main orchestration layer
- processar.sh is the primary document-processing entrypoint for a single file.
- integrar.sh is the end-to-end shortcut that takes a document plus user parameters and produces the filled spreadsheet from the template.
- These scripts are the top-level boundary between the user and the rest of the pipeline.
4. OCR ingestion boundary
- The OCR stage uses Azure Computer Vision credentials from environment variables:
- AI_SERVICE_KEY
- AI_SERVICE_ENDPOINT
- body.json appears to be the request payload template used when calling the Azure OCR endpoint.
- curl is required, so the OCR step is implemented as an HTTP API call from shell rather than through a dedicated SDK.
5. Text post-processing / normalization
- The repo includes Unix text-processing tools and scripts such as organizar.awk, plus sed, jq, and shell utilities.
- This layer reshapes the raw OCR output into a more regular intermediate form.
- Artifacts like output.txt, fin4pontos.txt, and outvertex.txt suggest staged outputs between OCR, AI interpretation, and final structured data.
6. Semantic interpretation with Vertex AI
- vertex.py is the Python component that talks to Vertex AI.
- The README indicates it uses vertexai.init(...), so it depends on Google Cloud application-default authentication via gcloud auth application-default login.
- This stage reduces assumptions about the document structure and helps recover time entries from noisy OCR text.
7. Spreadsheet generation layer
- excel.py is the Python component that writes the processed point data into Excel.
- The template-based workflow centers on modelo.xlsx, with a real employee workbook such as funcionario.xlsx as the target/output example.
- The script takes a start day, workbook name, sheet name, and employee name, so the Excel stage is parameterized rather than hardcoded.
8. Data contract between stages
- The pipeline is designed around a text intermediate representation rather than passing binary data between components.
- The practical handoff format is likely the processed point list in fin4pontos.txt, which is then consumed by excel.py.
- The README’s example sed cleanup step before Excel insertion indicates the final stage expects a strict text format.
9. Domain assumptions and constraints
- The repo encodes business rules for timesheet interpretation, such as:
- times are valid and relevant to the table,
- non-time numbers are rare,
- entry/exit ordering follows shift logic,
- documents are scanned/straightened images,
- absences and special days are marked.
- These assumptions are important because they shape how OCR errors and ambiguous handwriting are resolved.
10. Inputs, outputs, and sample assets
- pontos/ holds example source documents.
- modelo.xlsx is the spreadsheet template.
- funcionario.xlsx is an example filled workbook or target output.
- prompt/ likely contains the prompt text used for AI interpretation.
- output.txt, outvertex.txt, and fin4pontos.txt are trace/debug or intermediate outputs, useful for diagnosing each pipeline stage.
11. Runtime and environment boundaries
- Python is used for the AI/spreadsheet stages, while shell/Unix tools handle orchestration and text manipulation.
- The repo assumes a Linux-like environment; Windows users need extra tooling (awk, sed, jq).
- Required cloud setup spans two vendors: Azure for OCR and Google Cloud for Vertex AI.
12. How to draw the architecture
- A clean diagram would show:
- User / source document
- Shell orchestration layer (processar.sh, integrar.sh)
- Azure OCR service
- Text normalization layer (awk, sed, jq, intermediate text files)
- Vertex AI interpretation
- Excel writer (excel.py)
- Final spreadsheet output
- The key architectural idea is that this repo is a multi-stage document understanding pipeline, not a monolithic app.
Main entry points: excel.py excel.py · processar.sh processar.sh · vertex.py vertex.py · integrar.sh integrar.sh
Components 16
Entry & orchestration
Shell entrypoints that drive the document-processing pipeline.
- processar.sh · Primary single-file processing script.
processar.sh - integrar.sh · End-to-end shortcut from document to filled spreadsheet.
integrar.sh
OCR boundary
Azure OCR request/response handling and raw extraction artifacts.
- body.json · Request body template for the Azure OCR call.
body.json - output.txt · Raw OCR stage artifact.
output.txt
Text transform
Shell and text-processing stages that regularize OCR output.
- organizar.awk · AWK normalization step for OCR text.
organizar.awk - sed / jq · Shell text-processing utilities used to reshape intermediate data.
- fin4pontos.txt · Structured point list handed toward spreadsheet population.
fin4pontos.txt
Semantic interpretation
Vertex AI-based recovery of structured time-card entries.
- outvertex.txt · Interpreted text artifact produced by the AI step.
outvertex.txt - vertex.py · Python component that calls Vertex AI.
vertex.py
Spreadsheet output
Excel template filling and final workbook generation.
- excel.py · Python component that fills the workbook template.
excel.py - modelo.xlsx · Base Excel template for time-card population.
modelo.xlsx - funcionario.xlsx · Example target/output workbook.
funcionario.xlsx
Assets & samples
Input documents, prompts, templates, and example outputs.
Other components
- Azure CV · External OCR service boundary used via HTTP.
- Vertex AI · Google Cloud semantic interpretation boundary.
Connections 16
- pontos/ → processar.sh: input file · User-selected scan or photo enters the processing script.
- integrar.sh → processar.sh: invokes · End-to-end wrapper delegates to the main processing flow.
- processar.sh → body.json: builds request · Prepares the OCR payload for the Azure request.
- body.json → Azure CV: HTTP OCR · Shell script posts the payload to the OCR service.
- Azure CV → output.txt: raw text · OCR response is captured as a text artifact.
- output.txt → organizar.awk: normalize · AWK reshapes the OCR output into a cleaner intermediate form.
- organizar.awk → sed / jq: refine · Shell text tools perform cleanup and formatting.
- sed / jq → fin4pontos.txt: stage data · Intermediate structured text is produced for downstream use.
- fin4pontos.txt → vertex.py: interpret · Python reads processed text for semantic recovery.
- prompt/ → vertex.py: guidance · Prompt assets shape the interpretation step.
- vertex.py → Vertex AI: API call · Vertex client sends the document understanding request.
- Vertex AI → outvertex.txt: structured text · AI interpretation is stored as a text artifact.
- outvertex.txt → excel.py: consume · Spreadsheet writer consumes the interpreted points.
- modelo.xlsx → excel.py: template · Workbook template is used as the base for population.
- excel.py → funcionario.xlsx: write workbook · Final Excel file is generated from the template and processed data.
- integrar.sh → excel.py: orchestrates · Integrated flow reaches the workbook-writing stage.