Improve README.md (#62)

2025-11-16 20:13:20 +01:00
parent 93b6f7d88f
commit 3f2acdf07e
1 changed files with 74 additions and 41 deletions
--- a/README.md
+++ b/README.md
@@ -1,74 +1,107 @@
-# FairScan
+<p align="center">
+  <img src="app/src/main/ic_launcher-playstore.png" alt="FairScan icon" width="120" />
+</p>

-FairScan is an Android app to scan documents. It aims to be simple and respectful to users.
+<h1 align="center">FairScan</h1>

-"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.
+<p align="center">
+  An Android app to scan your documents —
+<br/><b>simple</b> and <b>respectful</b>.
+</p>

-## 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)
+<p align="center">
+  <a href="https://github.com/pynicolas/FairScan/releases"><img src="https://img.shields.io/github/v/release/pynicolas/FairScan?logo=github" /></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/pynicolas/FairScan?color=blue"></a>
+</p>
+<h3 align="center">
+  <b>Get it on:</b>
+  <a href="https://f-droid.org/en/packages/org.fairscan.app/">F-Droid</a> ·
+  <a href="https://play.google.com/store/apps/details?id=org.fairscan.app">Play Store</a> ·
+  <a href="https://github.com/pynicolas/FairScan/releases">GitHub</a>
+</h3>

-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.<br>
+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 |
+|------|---------|--------------|
 | ![](metadata/en-US/images/phoneScreenshots/1.jpg) | ![](metadata/en-US/images/phoneScreenshots/2.jpg) | ![](metadata/en-US/images/phoneScreenshots/3.jpg) |

+---
+
 ## 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:<br>
+https://github.com/pynicolas/fairscan-segmentation-model
+
+It's based on a fully public dataset that is available here:<br>
+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.