timi/scicam/README.md

SciCam Logger

A minimal Android camera logging tool for scientific archiving and inventory.

Philosophy

One tool, one job. Capture the image, log the metadata, and get out of the way. No AI. No cloud. No unnecessary processing.

Features

• CameraX preview with tap-to-focus.
• Lock toggle freezes Auto-Exposure (AE) and Auto-White-Balance (AWB) for consistent color across a batch.
• Barcode / QR scanner (ZXing) to auto-fill item_id.
• Manual ID fallback — type an ID if no barcode is available.
• Tagging — comma-separated tags written to the sidecar.
• JSON sidecar per image containing:
  • item_id
  • tags
  • timestamp
  • camera_settings (ISO, exposure time, aperture, focal length, lock states)
  • location (placeholder null for your archive API)
• Batch mode — UI retains the last item_id so you can shoot multiple angles.
• Public storage — images go to Pictures/SciCam/, sidecars to Documents/SciCam/ (API 29+) or the same legacy public folders (API < 29), both visible over USB MTP.

Tech Stack

• Kotlin
• CameraX (preview + capture + manual control via Camera2 interop)
• ZXing Android Embedded (barcode scanning)
• org.json (sidecar generation — no extra dependencies)

Build Instructions

Option 1: Android Studio

1. Open the scicam/ folder in Android Studio.
2. Sync Gradle.
3. Connect an Android device (API 24+) with USB debugging enabled.
4. Click Run.

Option 2: Command Line (host toolchain)

Requires Android SDK (ANDROID_HOME set) and a connected device or emulator.

cd scicam
./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk

Option 3: Docker (no local Android SDK needed)

Builds the APK in a container; adb runs on the Linux host for USB install.

cd scicam
./docker-build.sh
adb install app/build/outputs/apk/debug/app-debug.apk

Usage

1. Launch SciCam Logger.
2. Tap SCAN to read a barcode/QR code, or type an Item ID manually.
3. Enter comma-separated Tags (e.g., fragile, archive, 2024).
4. Tap the preview to focus.
5. Tap LOCK to freeze exposure and white balance.
6. Tap CAPTURE.
7. The image is saved to Pictures/SciCam/ and the metadata sidecar to Documents/SciCam/.

Output Example

Image

Pictures/SciCam/20250424_143052_ITEM-001.jpg

Sidecar

{
  "item_id": "ITEM-001",
  "timestamp": "20250424_143052",
  "filename": "20250424_143052_ITEM-001.jpg",
  "location": null,
  "tags": ["fragile", "archive"],
  "camera_settings": {
    "iso": 100,
    "exposure_time": "0.010000",
    "aperture": "1.80",
    "focal_length": "4.44",
    "ae_locked": true,
    "awb_locked": true
  }
}

Folder Locations by API Level

Android Version	Image Path	Sidecar Path
API 24–28 (Legacy)	/sdcard/Pictures/SciCam/	/sdcard/Documents/SciCam/
API 29+ (Scoped Storage)	Pictures/SciCam/ via MediaStore	Documents/SciCam/ via MediaStore

Both are accessible via USB file transfer (MTP) without ADB.

Next Steps / Extending

• Location: Populate the location field in MetadataLogger.kt once your archive API schema is ready.
• Custom grids / overlays: Add PreviewView overlay drawables in activity_main.xml.
• Focus distance slider: Integrate LENS_FOCUS_DISTANCE via Camera2 interop and a SeekBar.
• RAW capture: Upgrade ImageCapture to use ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY with setOutputFormat(ImageCapture.OUTPUT_FORMAT_RAW) on supported devices.