sam
3c77e9ab3e
Prep for public distribution. All user-facing strings, the README, the Gitea workflow step names/comments and the keystore example are now English. Follow-up i18n (string resources + locale files) is tracked in #5. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
118 lines
4.6 KiB
Markdown
118 lines
4.6 KiB
Markdown
# PaperScan
|
|
|
|
A local, privacy-conscious document scanner for Android. Scan paper documents with your
|
|
camera, automatically detect the edges, correct the perspective, and bundle multiple pages
|
|
into a single PDF. That PDF can be shared through Android or uploaded directly to your
|
|
self-hosted **Paperless-ngx**.
|
|
|
|
**Everything happens on the device.** Camera frames, edge detection (OpenCV) and PDF
|
|
creation never leave your phone. The only network connection is the optional upload to the
|
|
Paperless server you configure yourself. There is no AI or cloud processing.
|
|
|
|
## Features
|
|
|
|
- 📷 Camera preview with multi-page capture (add pages one by one)
|
|
- ✂️ Automatic edge detection + perspective correction (OpenCV), with manual corner adjustment
|
|
- 🎨 Per-page filters: color, grayscale, black & white (document mode)
|
|
- 🔄 Rotate, reorder and delete pages
|
|
- 📄 Export to a multi-page PDF (A4 or original size)
|
|
- ☁️ Direct upload to Paperless-ngx **or** share via the Android share sheet
|
|
- 🔊 Capture feedback: shutter sound (only when the ringer isn't silenced) + a brief flash
|
|
- 🔐 API token stored encrypted (Android Keystore / EncryptedSharedPreferences)
|
|
|
|
## Tech
|
|
|
|
Kotlin · Jetpack Compose · CameraX · OpenCV (`org.opencv:opencv` via Maven) ·
|
|
`PdfDocument` · OkHttp · DataStore. minSdk 26 (Android 8), target/compile SDK 35.
|
|
|
|
## Building locally
|
|
|
|
1. Open the project in **Android Studio** (Ladybug or newer). This automatically generates
|
|
the Gradle wrapper (`gradlew` + `gradle-wrapper.jar`).
|
|
2. Connect a device or start an emulator and press **Run**.
|
|
|
|
Or from the command line (after `gradle wrapper` once):
|
|
|
|
```bash
|
|
./gradlew assembleDebug # debug APK, no signing required
|
|
./gradlew assembleRelease # release APK, requires signing (see below)
|
|
```
|
|
|
|
The release APK ends up in `app/build/outputs/apk/release/`.
|
|
|
|
## Creating a signing key
|
|
|
|
Required for release builds (and therefore for updates that can overwrite each other).
|
|
|
|
```bash
|
|
keytool -genkey -v -keystore release.jks -keyalg RSA -keysize 2048 \
|
|
-validity 10000 -alias paperscan
|
|
```
|
|
|
|
Keep `release.jks` **safe and out of git** (already in `.gitignore`).
|
|
|
|
For local release builds, create a `keystore.properties` in the project root
|
|
(see `keystore.properties.example`):
|
|
|
|
```properties
|
|
storeFile=/path/to/release.jks
|
|
storePassword=...
|
|
keyAlias=paperscan
|
|
keyPassword=...
|
|
```
|
|
|
|
## Building via Gitea Actions
|
|
|
|
The workflow `.gitea/workflows/build.yml` builds a signed release APK on every version tag
|
|
(`git tag v0.1.0 && git push --tags`) or via a manual run, and publishes it as a **Release**
|
|
with the APK attached as a downloadable asset.
|
|
|
|
Add these secrets under **Settings → Actions → Secrets** in your Gitea repo:
|
|
|
|
| Secret | Contents |
|
|
| --- | --- |
|
|
| `SIGNING_KEYSTORE_BASE64` | `base64 -w0 release.jks` (the keystore as base64) |
|
|
| `SIGNING_STORE_PASSWORD` | keystore password |
|
|
| `SIGNING_KEY_ALIAS` | e.g. `paperscan` |
|
|
| `SIGNING_KEY_PASSWORD` | key password |
|
|
|
|
The build uses env vars, so nothing sensitive ends up in the repo.
|
|
|
|
> The build runs in a container (`mingc/android-build-box`), so the Actions runner must be
|
|
> **x86_64** — the Android build tools (aapt2) are x86_64-Linux only and won't run natively
|
|
> on an ARM64 runner.
|
|
|
|
## Setting up Paperless-ngx (in the app)
|
|
|
|
1. Create an API token in Paperless: **Settings → profile → API token** (or via `/api/token/`).
|
|
2. In PaperScan, open the gear icon → enter the **server URL** (e.g. `https://paperless.home.lan`)
|
|
and the **token** → **Test connection** → **Save**.
|
|
|
|
Prefer **https**; with `http://` the app warns that the token and documents travel over the
|
|
network unencrypted.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
app/src/main/java/eu/geyskens/pdfscan/
|
|
├── PaperScanApp.kt # Application; loads OpenCV native libs
|
|
├── MainActivity.kt # Compose host + navigation
|
|
├── ScanViewModel.kt # scan session, rendering, export, upload
|
|
├── data/ # Page model, ScanFilter, SettingsRepository
|
|
├── scan/ # EdgeDetector, ImageProcessor, BitmapIo (OpenCV)
|
|
├── pdf/ # PdfBuilder (multi-page PDF)
|
|
├── paperless/ # PaperlessClient (OkHttp REST + task polling)
|
|
└── ui/screens/ # Camera, Pages, Crop, Export, Settings
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
Tracked as issues in the repository:
|
|
|
|
- Live edge-detection overlay while aiming (like Microsoft Lens)
|
|
- Internationalization: extract UI strings to resources + add translations
|
|
- Batch import scans from the gallery
|
|
|
|
> OCR is intentionally **not** done on-device: Paperless-ngx already runs OCR (via
|
|
> OCRmyPDF/Tesseract) when it consumes the uploaded document.
|