From 3f2acdf07ed2b25ab0707f4870c3740239bfc555 Mon Sep 17 00:00:00 2001
From: pynicolas <6371790+pynicolas@users.noreply.github.com>
Date: Sun, 16 Nov 2025 20:13:20 +0100
Subject: [PATCH] Improve README.md (#62)
---
README.md | 115 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 74 insertions(+), 41 deletions(-)
diff --git a/README.md b/README.md
index e73f831..615dc02 100644
--- a/README.md
+++ b/README.md
@@ -1,74 +1,107 @@
-# FairScan
+
+ 
+
-FairScan is an Android app to scan documents. It aims to be simple and respectful to users.
+FairScan
-"Simple" means that users should get a clean PDF in seconds and without thinking:
-- The user interface should be super clear, with no distractions.
-- The scanning process should be obvious.
-- The app should automatically handle all image processing and PDF generation tasks.
+
+ An Android app to scan your documents —
+
simple and respectful.
+
-## Get FairScan
-- [F-Droid](https://f-droid.org/en/packages/org.fairscan.app/)
-- [Google Play](https://play.google.com/store/apps/details?id=org.fairscan.app)
-- [GitHub releases](https://github.com/pynicolas/FairScan/releases)
+
+ 
+ 
+
+
-See also:
-- [fairscan.org](https://fairscan.org)
-- [the blog](https://fairscan.org/blog/)
+---
+
+FairScan is an Android app to **scan documents quickly, easily and privately**.
+
+It's designed to be **simple**: users get a clean, shareable PDF in seconds, with no manual adjustments.
+And **respectful**: open source, minimal permissions, no tracking, no ads.
+
+- Website: https://fairscan.org
+- Blog: https://fairscan.org/blog/
+
+---
## Screenshots
-| 1. Scan | 2. Preview | 3. Save & Share |
-|---------------------------------------------------|---------------------------------------------------|---------------------------------------------------|
+
+| Scan | Preview | Save & Share |
+|------|---------|--------------|
|  |  |  |
+---
+
## Features
-- Automatic document detection (using a [custom image segmentation model](https://github.com/pynicolas/fairscan-segmentation-model))
-- Automatic perspective correction
-- Automatic image enhancement
+- **Clear, distraction-free interface**
+- **Easy scanning process**: scan → preview → share
+- **Automatic document detection** using a custom segmentation model
+- **Automatic perspective correction**
+- **Automatic image enhancement**
+- **Fast PDF generation** with no manual adjustments
+- **Fully offline** – the app has *no* internet permission
+- **Minimal permissions**
+- **Open source**, GPLv3
+
+---
## Compatibility
-FairScan should be compatible with all devices that:
-- run Android 8.0 or a more recent version
-- have a camera
+FairScan works on any device that:
+- runs **Android 8.0+**
+- has a camera
-## Privacy
+---
-- All data stays on the device. As of today, FairScan does not access the internet.
-- Minimal permissions:
- - Camera
- - WRITE_EXTERNAL_STORAGE: only on Android 8 and 9 to save generated PDFs in the Download directory.
-- Zero trackers.
+## Technical details
-## Main dependencies
+FairScan uses:
-- [Jetpack Compose](https://developer.android.com/compose) for the user interface
-- [CameraX](https://developer.android.com/media/camera/camerax) to capture images from the camera
-- [LiteRT](https://ai.google.dev/edge/litert) to run the segmentation model for automatic document detection
-- [OpenCV](https://opencv.org/) for:
- - perspective correction
- - image enhancement
+- [Jetpack Compose](https://developer.android.com/compose) for the UI
+- [CameraX](https://developer.android.com/media/camera/camerax) for image capture
+- [LiteRT](https://ai.google.dev/edge/litert) to run the custom segmentation model for automatic document detection
+- [OpenCV](https://opencv.org/) for perspective correction and image enhancement
- [PDFBox-Android](https://github.com/TomRoush/PdfBox-Android) for PDF generation
-Kudos to the developers of those projects!
+---
+
+## The segmentation model
+
+FairScan uses a custom-trained image segmentation model to detect documents:
+https://github.com/pynicolas/fairscan-segmentation-model
+
+It's based on a fully public dataset that is available here:
+https://github.com/pynicolas/fairscan-dataset
+
+The build system automatically downloads the model using
+[`download-tflite.gradle.kts`](app/download-tflite.gradle.kts).
+
+Related blog posts:
+- [*Making document detection more reliable*](https://fairscan.org/blog/automatic-document-detection/)
+- [*Building a public dataset for FairScan*](https://fairscan.org/blog/building_a_public_dataset/)
+
+---
## Build
To build an APK:
+
```bash
./gradlew clean check assembleRelease
```
-
To build an Android App Bundle:
```bash
./gradlew clean check :app:bundleRelease
```
-### Note on the segmentation model
-The builds automatically downloads the segmentation model from
-[fairscan-segmentation-model](https://github.com/pynicolas/fairscan-segmentation-model).
-This is done in [`download-tflite.gradle.kts`](app/download-tflite.gradle.kts).
-
## License
This project is licensed under the GNU GPLv3. See [LICENSE](LICENSE) for details.