Spring Boot OCR API workshop

Latest stable Based on Image release 0.3.0

Runnable example

Problem

This Spring Boot 4 workshop exposes bluetape4k-images-ocr through a multipart endpoint. It parses language codes, passes host tessdata configuration to an injectable OcrEngine, and separates invalid requests from native OCR availability failures.

When to use it

Use it when introducing OCR into a Spring MVC application or when you need a testable boundary around Tess4J/Tesseract. It is a focused endpoint example, not a document-processing platform.

Coordinates

The example itself is not published. Choose one bluetape4k-dependencies version and consume bluetape4k-images-ocr; keep the OCR module aligned through that central version rather than pinning it independently.

Core concepts

OcrEngine is injected; TesseractOcrEngine is only the production default.
eng+kor and eng,kor become listOf("eng", "kor").
example.ocr.tessdata-path is host configuration and is not accepted from each request.
IllegalArgumentException maps to 400; OcrException maps to 503.

Quick start

Tests require JDK 21+ only. Real OCR requires Tesseract and matching traineddata.

brew install tesseract tesseract-lang
tesseract --list-langs
./gradlew :spring-boot-ocr-api:bootRun

curl -F "file=@sample-ko.png;type=image/png" \
  "http://localhost:8080/api/ocr?languages=eng+kor"

Configure a non-default traineddata directory with example.ocr.tessdata-path.

API by task

Task	Release API
Submit OCR	`POST /api/ocr` multipart field `file`
Select languages	query parameter `languages`
Configure native data	`ExampleOcrProperties.tessdataPath`
Run recognition	`ImmutableImage.suspendExtractText(options, engine)`
Report result	`OcrTextResponse(text, languages, characterCount)`

Recommended patterns

Inject the native engine, keep host paths in configuration, validate content type before decoding, and give native-unavailable failures a different status from client errors. Fake the engine in controller tests; reserve host OCR smoke tests for a compatible environment.

Integrations

The workshop uses bluetape4k-images-ocr and core image decoding. Pair it with spring-boot-image-api only after deciding whether OCR runs before or after durable storage.

Configuration

Supported request media types are JPEG, PNG, WebP, and GIF. The language default is eng. Set example.ocr.tessdata-path when Tesseract cannot find traineddata through its host defaults or TESSDATA_PREFIX.

Failure modes

400 bad_request: empty upload, missing content type, unsupported media type, or malformed languages.
503 ocr_unavailable: Tesseract/native bridge or requested traineddata is unavailable.
Incorrect text: verify installed languages, input quality, orientation, and preprocessing; successful HTTP execution does not guarantee OCR accuracy.

Operations

Add request-size limits, timeouts, concurrency controls, authentication, and rate limiting in the owning service. Avoid logging source documents or full recognized text unless the data policy explicitly permits it.

Testing

./gradlew :spring-boot-ocr-api:test

MockMvc and a fake OcrEngine verify multipart success, eng+kor parsing, tessdata propagation, unsupported media rejection, and 503 failure mapping without host Tesseract.

Workshops and learning path

Read the OCR module manual and run this workshop’s fake-engine tests.
Install Tesseract and confirm language packages with tesseract --list-langs.
Exercise a real text-heavy image and observe quality separately from API correctness.
Compare ktor-ocr-api to see the same domain boundary with explicit multipart streaming.

Limitations

Authentication, queues, persistence, batch OCR, preprocessing policy, and rate limiting are outside this quickstart. OCR quality and language coverage are host-dependent.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.3.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.