jasonklotzer/dcm2bq repository overview

DCM2BQ — DICOM → BigQuery service and CLI

Overview

DCM2BQ extracts metadata and rendered content from DICOM Part 10 files, generates vector embeddings (images, Structured Reports, encapsulated PDFs) using Google Vertex AI, and writes metadata and embeddings to BigQuery for semantic search and analytics. The image includes native DICOM tooling (DCMTK, GDCM) and can run as an HTTP service (Cloud Run) or as a local CLI.

Key features

Parse DICOM files and convert metadata to JSON. Render DICOM images and extract text from SR/PDF. Generate vector embeddings for image, SR, and PDF content. Write metadata and embeddings into BigQuery (metadata & embeddings tables). Event-driven ready: process GCS → Pub/Sub push events as a Cloud Run service. CLI mode for local testing, batch processing, and debugging. Sample BigQuery DDL/queries and Terraform deployment helpers included.

Usage examples

Run containerized service with a mounted config file: docker run --rm -p 8080:8080 -v /path/to/config.json:/app/config.json:ro -e DCM2BQ_CONFIG_FILE=/app/config.json jasonklotzer/dcm2bq:latest

Run CLI inside container to dump metadata: docker run --rm -v $(pwd):/work -w /work jasonklotzer/dcm2bq:latest dcm2bq dump ct.dcm

Configuration

DCM2BQ_CONFIG_FILE — Path to a JSON file containing the entire service configuration (must be full object; no merging). DCM2BQ_CONFIG — JSON string of the full configuration object (alternative to file). See config.defaults.js for default values and example structure. Important: Environment-configured overrides replace the default configuration entirely — provide the full configuration object.

Networking & ports

Exposes HTTP on port 8080 (default). Health/version endpoint: GET /

Entrypoint & CLI

The image runs the Node service (index.js) and provides a dcm2bq CLI command inside the container (defined in package.json).

Security & credentials

The container does not include GCP credentials. Use Workload Identity (Cloud Run) or mount credentials locally via GOOGLE_APPLICATION_CREDENTIALS for local testing. Do NOT bake credentials into images.

Recommended tags & automated builds

Tag strategy: semver (e.g., 1.1.5), and latest for main. Automated build triggers: GitHub release tags → publish semver image; branch main → latest. After build, run a smoke check: start container and hit GET / expecting JSON {name,version}.

Source & license

GitHub: https://github.com/GoogleCloudPlatform/dcm2bq⁠ License: Apache-2.0

Notes

The image includes DCMTK and GDCM; if you build from source locally, ensure those native packages are installed in your environment. For Cloud Run deployments, allocate sufficient memory for large DICOM files and embedding operations.