FairScan Blog

Why I made FairScan open source (and chose the GPL)

2026-08-30T00:00:00Z

When I started FairScan, it was the first time I was publishing software on my own. Previously, almost all the code I wrote was on behalf of my employer, and the rest was just for me, with no intention of being published. From day one, it was obvious to me that FairScan would be open source, and the GNU General Public License (GPL) felt like the natural choice. I knew what it meant and didn't give it much thought, because my attention was on all the technical topics I had to learn to reach my goal.

What did give me pause was something else: once the code is out there, I have no real control over what happens to it. Someone can fork it, rebrand it, build a product on top of it. The GPL legally requires derivative works to stay open source, but I can't enforce that in practice: if a company somewhere quietly used my code in a closed product, I would probably never even know. That's a risk I knew I was taking, and I had to be at peace with it before I clicked to make my repository public.

Why was it obvious to me that FairScan should be open-source and use the GPL? I believe it's the combination of several points of view I have on the project.

As a user

As a user, I want an app that keeps my data strictly private, that doesn't track me and doesn't force me to see ads. More generally I don't want it to have any behavior that is against my own interest, and that's what I call a respectful app. Some of those behaviors are quite visible (for example: ads) and some are hidden. App publishers make a lot of claims on how much they care about privacy and other things but there's no external control. Those claims may be phrased vaguely ("Your privacy is our strongest concern", "we use data to improve our service") and they rarely explicitly mention topics where you may not like the truth: how often did you read "we train our models with your data"?

How an app actually behaves is defined by its source code: the code is not a claim, it's what's executed. Most often, the source code is not publicly available because it's considered a trade secret. Except for open-source apps. If an app is open source, a developer can inspect its code, and check its actual behavior. A developer may also modify the code and distribute a new application based on that. That gives users a form of control, even if they don't understand code themselves. If an open source app behaves in a way that many people don't like, it's quite likely that someone knowledgeable will distribute an alternate version of it. This is one of the most important freedoms I believe software can give its users.

I personally use open source apps as much as possible, whether on my computer or my phone. Of course, that can't be the only criterion: an app should first help me get the job done, and in a way that's easy and efficient for me. Still, the fact that an app is open source means I'm in control of the software I use, and that's crucial to me.

As a developer

As a developer, I prefer to develop apps that I use myself. That's rarely the case when working for an employer: my job could be to work on software whose purpose is unfamiliar to me, and to make it behave in ways that I don't agree with. As an independent developer, I can decide what I work on. FairScan started with a need I had and a solution I wanted to build. I'm not FairScan's only user, but I'm its first user.

Why share it, though? Maybe I could have developed an app just for me: it would fill my need and I would be in control of it. I must say I never really considered that option: I would probably not have started FairScan if it was just for myself. The main reason is that I want my work to be useful. There's a real satisfaction in knowing that thousands of people use FairScan. Making it open source was the only way to share FairScan along with the freedom I want to get as a user.

One question everyone publishing open source code has to answer is which license to use. In fact, there's a major difference among the most common open source licenses. On one side, permissive licenses such as the Apache License and the MIT license allow users to do almost anything with the source code. On the other side, the GNU General Public License gives mostly the same rights but requires derivative works (apps that re-use the code) to be also open source and use an equivalent license.

For FairScan, the choice seemed easy to me. I chose the GPL because I don't want my work to be re-used in an app that gives less freedom to its users. In a way, it's about being consistent: if, as a developer, I build software that provides the freedom I want to get as a user, then all users of derivative works should get the same. I know it can be a significant constraint for developers who want to re-use my code but I'm fine with that: I believe it's a constraint worth accepting for developers who share my views.

Open source is not incompatible with making money, it can even be a business strategy. For example, Google open sourced Android's core and it provides open source libraries for Android apps (FairScan uses several of them). And companies such as Proton publish open-source apps as part of their business model. On my side, I don't see how I could build a business around FairScan and I have no intention to go that way. I started accepting donations a few months ago: that's a model I'm more comfortable with. Thank you to all the people who donated!

As a citizen

As a citizen, there are quite a few things I don't like in the world I live in. Complaining doesn't help me feel better. Acting does, at least a little. I guess it started by paying attention to the sustainability of the things I consume, and that includes the software I use.

But being a software engineer, I'm not just a consumer of software, I'm also in a position to produce it. Software has a huge impact on our lives, from personal communication to public services. But to what extent do users get to decide how software should behave? I believe that free and open-source software (FOSS) can help people take back some control over it. For me, joining April, a French association promoting free software, was one way to put that into practice. But building FairScan the way I did is another, more direct one.

And when I think about what to build, I come back to the same question: which software do people actually need? I believe that scanning a document is a basic need today: it's required for all kinds of administrative tasks, for people who don't necessarily know or care about tech. Should getting that done require paying, watching ads, or giving away private data? I don't think so, and yet this is so often the model for "free" apps.

By publishing FairScan's code, and also the dataset I built to train its detection model, I hope to contribute a small piece to what's sometimes called the digital commons: things that exist for everyone to use and build upon. It's a modest contribution and it can continue to exist beyond whatever I personally decide to do with the project. As a user wrote on the Play store:

It's FOSS!! So I know it will still be around in ten years without ad nor paywall nor nonsense nor malice.

Today, I still have that doubt: if someone violates the GPL, I will most likely never know. But that's a risk I accept to move forward.

In the end, I see FairScan less as an "open source app" than as a respectful app, but making it open source, with the GPL specifically, is what makes that possible.

Keeping FairScan simple isn't simple

2026-07-31T00:00:00Z

I present FairScan as a "simple and respectful" app. But those are not just words to talk about FairScan, they are key values that drive development. I dedicated one of my first blog posts to explain what I see as a "respectful" app and I think that "simple" also deserves a few explanations.

What I mean by "simple"

Let's first clarify what I mean when I describe FairScan as a "simple" app.

Essentially, I'm trying to make an app that's as easy to use as possible. For an app like FairScan, the scanning process should be straightforward and require a minimal number of actions from users. I believe that an app with few buttons and options makes it easier for users to get the job done.

That's more likely to happen for an app that focuses on doing one thing. FairScan is about scanning documents. It's not about storing them or editing them. Storing user data implies some responsibility and I think it's better handled by a dedicated app. Users can combine apps that have a small but well-defined scope: the Android system provides an infrastructure to make that fluid.

I should also make it clear that what I mean by "simple" is definitely not "basic". I put a lot of effort in automatic processing so that users can get a good scan without any manual adjustment. The app takes care of document detection, perspective correction, color detection, brightness and contrast enhancements... What you see today took me a lot of research and testing so that users can "get a scan" without having to think about what it involves behind the scenes. So the fact that FairScan is simple for users certainly does not mean that it's simple to develop.

Overall, I think that my goal for a simple app is to reduce the mental load for users as much as possible.

Why building a simple app

The main reason for me to build a simple app is that I'd like it to be usable by everyone. My goal is that FairScan is not only used by advanced users who know where to find respectful apps. It's therefore crucial that it's easy to use.

It's also because that's the kind of app I want to use. When I have to scan a document, it's often for administrative purposes and I don't want to think about it, I just want to get a result fast. I'm sure many people feel the same: they don't enjoy scanning documents, they just want to get the job done with a tool that stays out of the way.

I also enjoy looking deeply at a problem, understanding its essence, and figuring out how to present it as clearly as possible.

For all those reasons, I think a simple app is the only kind I could build.

It's a deliberate choice that has been driving FairScan's development since its inception. It's a major driver for every decision and it's really about favoring clarity and ease of use over PDF perfection and manual control.

Let's look at how that drives FairScan's development.

A continuous quest for simplicity

The app evolved a lot since its first public version. At the time, FairScan's workflow required users to go through 4 screens to get a scan. At some point, I received a request from someone who was using the app to scan many documents one after another and would have liked a specialized workflow requiring less clicks. I was reluctant to add an option for that and I started to think about how to make the workflow simpler for everyone.

I made changes in that direction in several steps.

The screen to preview the result and adjust it looked like a questionable step of the workflow. It's useful in some cases but the app is supposed to give a good result without adjustment. The screen now only appears when tapping a thumbnail and I believe that makes more sense.
The app always displayed a home screen on startup, and the end of the scanning workflow also led back to that screen. It contained a list of previously saved PDFs which was raising questions. I dropped the home screen.

It's not a flawless process though. I had to reintroduce an explicit choice on startup to resume an ongoing scan when there's one: the removal of the home screen had made that choice implicit and that prevented new users from understanding what a "scan" means in FairScan.

The result is that there are now only 2 screens left in the scanning workflow. Over the past year, FairScan improved on many aspects but it's now also simpler for everyone.

Adding features and keeping it simple

The app also had to provide more and more value to users, and I didn't want that to impact how simple it is.

As an example, FairScan used to produce PDFs without caring for the physical dimensions of documents until recently. That was a problem, at least in some cases, and users asked for a way to force a PDF paper format such as "A4" or "Letter". I worked on a different way to address that problem that seemed more aligned with FairScan's approach. I found technical ways for the app to detect physical dimensions in many cases. As a result, FairScan is now able to detect standard formats such as A4 and generate PDFs that include this information in a fully automated way.

That raises the question of what's a "feature". Users asking for new features usually expect to get new buttons or new options. In the case I just described, nothing changed in FairScan's user interface, the only visible impact is the generated PDF. All users benefit from this new ability without having to do anything about it. It's a kind of feature that many people will never notice.

Simple vs. user control

Some requests don't have such a clean answer.

Quite a few people came to FairScan because it's respectful, in particular it doesn't suck up user data or display ads, which is not very common. People who care for that want control over the apps they install. The problem is that it's harder to make an app that's both simple and gives a lot of control to users. That requires additional buttons or options and it makes the user interface more complex. Of course, it also makes the app more complex to develop and maintain.

I felt this tension only a few weeks after releasing version 1, when early adopters requested the ability to manually define document edges. That's something I didn't want to do. I saw automatic document detection as the basis of FairScan's value, what makes it possible to build a simple app to scan documents. I knew what I had implemented was far from perfect and I wanted to get feedback to improve it. Unlike other aspects of a scan (for example: brightness), document edges are not a question of personal preference: they're either right or wrong. For me, introducing a manual control meant giving up on that and acknowledging that FairScan can't be what I want it to be.

I resisted for a long time. I worked a lot on automatic document detection: I looked for a different segmentation model, produced hundreds of new images for the dataset, and researched a new algorithm to make a quad out of a segmentation mask. I believe the app got significantly better.

And yet, for some users, it was still a source of frustration, and I could feel it. I received carefully written requests but also 1-star reviews on the Play store, and GitHub comments explaining to me the basic principles of software development and user experience. I can't say I'm indifferent to that.

I resisted up to version 1.21.0, when I received a very well-crafted contribution (thank you Philipp Hasper!) that implemented a new screen to manually define document edges. As the screen to preview and adjust the scan was now out of the main workflow, I felt it was acceptable to add a button for that.

I guess that's the kind of tradeoff I have to accept if I want FairScan to reach some day a wider audience.

Standing by simplicity

A simple app is still the only kind I'm interested in building and it's been a key value since I started FairScan. The result is an app that's "not impressive" (as I sometimes read), at least at first sight. I also had to say "no" to some feature requests. And I know many people associate "simple" with "low value". The real challenge for me is to be comfortable with that. Simplicity is almost invisible. When it succeeds, people rarely notice it, they simply get their work done. That's exactly what I'm aiming for. I spent a lot of effort so that users can get a good scan without thinking about what it takes. I'm not sure I'll always make the right call on where to draw the line, but I want FairScan to be an app that "just works".

When a scan becomes a searchable PDF

2026-06-17T00:00:00Z

Let's say that you signed a 5-page work contract. You have a paper document but no electronic version. Now you want to find a particular clause in the contract. How can you find it quickly? If you scan it with FairScan, you can now get a PDF which you can directly search for text. You may also copy any text from it, for example the paragraph you were looking for, and paste it in another application. This is the result of a text recognition system, which is often referred to as OCR (Optical Character Recognition).

An invisible text layer

When you scan a document, what you get is basically an image of the document. It's often stored in a PDF file and your PDF viewer displays this image, containing the pixels of a signature, the pixels of a logo, or the pixels that make the characters of a word. But to your PDF viewer, it's just the pixels of an image, and you can't search for text.

OCR is about identifying which pixels belong to text and reconstructing the text information they contain: which words and where they are located. The PDF file can then contain both the image and an invisible text layer. That's the recipe for a useful illusion:

You still see the document exactly as it is in the image
When you search for text, your PDF viewer highlights an area where you see a word that matches your search
When you point at an area of the image where you see a word, the cursor lets you select the word and copy it

Now you know the trick! And getting searchable PDFs like that out of FairScan is what I wanted to do.

Why now?

That looks nice, so why didn't FairScan have it before? That's because FairScan wasn't ready for it: I wouldn't be comfortable if FairScan was giving you wrong text half of the time. To get good results from an OCR engine, you need to provide it a readable image. If it's hard to read for a human, it's certainly also hard to read for an OCR engine.

Over the past year, I worked on different parts of FairScan's automatic processing to transform photos of documents into PDFs that are easy for humans to read:

document detection
perspective correction
shadow reduction
brightness and contrast enhancement

All this work on image processing helped FairScan produce clean PDFs and can now also contribute to making text recognition effective.

Implementing OCR in FairScan

Developing an OCR engine is quite hard. It was definitely out of the question for FairScan. I use Tesseract, an open source project that was initiated 40 years ago at HP.

Tesseract can be integrated easily into an Android app and covers about 120 languages. To avoid increasing drastically the app download size, language-specific data is not included in the app: you will have to download it separately for each language in FairScan's settings screen.

Like all the other parts of FairScan's scanning process, OCR runs on your device: your data is not sent to any server to be processed. This is unlike many mobile apps that rely on cloud processing to achieve the same task. On a mobile device, OCR typically takes a few seconds per page. That's significantly more than the other processing steps in FairScan, but still fast enough to remain practical for everyday scanning.

The challenge of PDF fonts

Making Tesseract run inside FairScan wasn't particularly difficult. Generating PDFs that work reliably across different writing systems turned out to be much harder.

PDF files need to know about fonts, fonts that cover the characters used in the file. Which font should FairScan use to generate PDFs? Tesseract can read many languages like English, Russian or Chinese. So we need a font for the latin alphabet, the cyrillic alphabet or Chinese characters. Fonts can be huge and that could impact both the app download size and the size of the generated PDFs. The irony is that, for invisible text, users never see the characters produced by the font. But PDF still needs a font for the text.

My research led me to the Adobe NotDef font: it renders all Unicode characters (covering all writing systems) the same way. As it's a tiny file, it looked like a good solution to avoid file size issues. However, because this font covers so many characters, the library I use to generate PDFs takes a couple of seconds to load it on my phone. I didn't manage to solve that and looked for another solution.

In fact, Tesseract itself can render PDFs. It faces the exact same problem and found a solution for it based on a kind of fake font. I couldn't use that directly because FairScan needs direct control on the PDF, for example to feed information about the physical dimensions of the document. But I took a lot of inspiration from what Tesseract does to generate PDF files. It requires hand-crafting PDF, which I never did before, but it works: it produces PDFs for all kinds of characters very fast and with a tiny font.

Keeping it simple

The technical solution I worked on for OCR was less important to me than how OCR should impact user experience. And it was clear to me that this impact should be minimal. OCR is not FairScan's core feature, and I didn't want OCR to break FairScan's main promise: its simplicity.

So the way OCR appears in FairScan's user interface is basically as an option to enable. More precisely, you choose which languages are enabled. Once it's done, OCR runs transparently, as part of the export. Nothing changes in the scanning process. The difference is in the generated output: you get a PDF where you can search and copy text.

Enabling more than one language for OCR makes it possible to extract text in multilingual documents. Be aware that processing may be slower and less precise. You can also disable all languages: that effectively disables OCR.

Known limits

It's not perfect and it's not as simple as I wish it was. I like everything to be automatic in FairScan but there is no automatic language detection. You have to enable the appropriate language(s) to get good results. I guess that shouldn't be a big problem: I expect that almost all documents you scan are always in the same one or two languages.

Also, let's state it clearly: you shouldn't expect to get acceptable results on handwritten text. That's a much harder problem and I believe it would go beyond FairScan's scope.

I also expect OCR quality to improve gradually over time. I already noticed that detection is poor on documents with very dense text, for example dictionary pages. I hope user feedback will help identify other cases that need attention.

A scanned document is often more useful when it can be searched, copied, and indexed like any other digital document. OCR makes that possible. FairScan's goal is still the same: turning paper documents into useful PDFs. OCR doesn't change that goal. It simply makes those PDFs more useful once they've been created. Still, OCR is often perceived as an "advanced feature". I hope that FairScan can contribute to bringing it to more people, in a simple and respectful way.

Donations, without expectations

2026-04-19T00:00:00Z

I give FairScan to everyone who wants to use it. The app is free and doesn't include any behavior that goes against users' interest: no ads, no tracking, no collection of your data, no premium version... That's possible because FairScan does not have to serve the interests of a business.

I'm an independent developer doing all kinds of tasks for FairScan:

software development (of course)
product management
researching image processing algorithms
producing a dataset for the segmentation model
answering e-mails and comments on GitHub issues
and many other things.

I'm definitely more comfortable for some of those tasks than others, but I see the project as a whole. As part of a normal job, it would be awkward for a developer to spend time on repetitive tasks that can be outsourced like creating "fake" documents and annotating data to train a model. I see it differently because FairScan is "my" project: I do what it takes to make a great app for users.

I spend most of my time on FairScan, and I now consider it as my job, even if I don't make money out of it. My main interest is having a positive impact and seeing people use the software I build. I made money in my previous jobs and, for now, I can afford to work without making money.

When I published FairScan, I received emails thanking me for the app, and that was quite rewarding. Some people wrote that they would like to give me money. I also appreciated those messages, but I hadn't set up a way to receive donations. I didn't see it as a priority as the app had very few users and even fewer potential donors.

I also received emails asking me to implement specific features, and, even though they were always kind, that was harder to manage. What I'm trying to build with FairScan is not the typical open source app. I'm not looking for ideas of features to add and I'm not trying to cover all the various needs of "power users". I'm trying to build an app that is simple and consistent. Something that can be used by everyone, even if not everyone likes it. I had to say "no" or "later" to many feature requests, and that was definitely not easy for me.

Adding money into that would have made things worse. When I received an email that mentioned both giving money and features to add, I took it as a clear signal: a few days later, I added an explicit statement on my website to decline all donations. Accepting money would have led to implicit expectations that I couldn't manage. Even if that wasn't intentional, it would have put pressure on me to implement features I didn't believe in, to diverge from the direction I gave to my project.

Time has passed. Little by little, feedback has helped me improve all areas of the automatic processing, which is the core of the app: document detection, cropping, color detection, brightness and contrast enhancement... This is not about "features", it's what most people would see as the basis of a scanning app without being able to articulate it. In addition to that, I did implement a few of the requested features, and the UI is even a bit simpler than it was. Overall, FairScan got more mature and it gets closer to what I wanted to build: an app that "just works".

The reviews on the Play Store and the messages I receive also tell me that many people enjoy the app and the fact that it's simple. I still feel a bit uncomfortable saying "no" to feature requests but I'm now much more confident about the direction I gave to FairScan.

The app is now quite decent but I know it's still far from perfect. I see a lot of things I would like to improve or start to tackle in FairScan. And based on what I already did, I know it will take time and effort.

I can continue working on FairScan without making money but I'm not sure how realistic it is in the long run and I can't pretend it's a good model for open source development.

I believe that donations could now help me, at least symbolically. It would help me feel some form of support and recognition for the work behind FairScan. That, in turn, could make it easier to find energy to work on tasks that are not quite enjoyable but still necessary.

Let's try something new for me: I'm going to update the website to now accept donations.

If you're willing to donate, I will gratefully receive it provided that we agree on one thing: it should not lead to any kind of expectation from your side. The same way I give FairScan with no expectation to every person who wants to use it. I don't want to commit on implementing any specific feature and, since life is unpredictable, I can't commit to work on FairScan for the next five years. I hope you will understand it.

Working as an independent open source developer is not a typical job and I'm still learning how to frame it. I'm already happy to have made FairScan grow so far and I hope I can make my effort sustainable. I want to keep going as long as it makes sense.

Working on FairScan or getting a "real job"?

2026-04-18T00:00:00Z

I've been working actively on FairScan for almost a year now. Why do I spend my time working on an open source project rather than getting a "real job"? What drives me? To explain that, I have to write about myself, much more than I did so far in this blog. That feels a bit uncomfortable but it can help convey what I'm trying to achieve.

Over the last 25 years, I had several jobs as a software engineer. The last one was for a company producing software for developers. I worked with passionate people and I learned a lot about software engineering, product management, and team collaboration. I also found a culture that resonated strongly with my own beliefs. It was an amazing experience. However, after 10 years, my job had changed to being a manager and I wasn't happy about it. Moreover, the company had grown from 25 to 500 employees and the culture was dissolving, becoming something I no longer recognized. It was a bit heartbreaking but I had to turn that page, time had come for me to leave.

What next? Life is short, and sometimes it reminds you of that. So what's important to me? When I think about this question, my head gets full of the concerns I have about where the world is going. I know I can't change the world but I just can't stay doing nothing about it. There are plenty of domains in my daily life where I try to be consistent with what I believe in, but my job is the most crucial part of it, it's where I spend a significant proportion of my time. I need sense, I need to feel that I contribute to something useful.

I briefly tried working as a maths teacher but I failed. I would love being able to do that: helping other humans grow, finding ways to explain concepts, giving keys to understand the world... But I miss crucial skills: managing a group of 25 or 30 teenagers is just impossible to me and I probably knew it before trying. Even though, I tried. It was an intense experience of just a few weeks but I have no regret about it. Back to doubt.

I could probably find a job as a software engineer in a bank or some other business that needs my skills. But I feel I would most likely contribute to making the world worse than it is, having an impact that is opposite to what I want. It would be easy to say that "I have no choice", but I believe that would be wrong.

Let's take a step back. What's a good job for me? I guess it's a lot about how much I enjoy it and the sense I get out of it. I also expect to get money from it, and I need to have the required skills. It looks like an equation that is difficult to solve. Sense is what I need most. For now, I can afford to work without making money, so let's take it out of the equation. That's radical, but it opens new possibilities.

What are my skills? Writing good software, and designing products that make sense, I believe. I can put those skills to work, not to build any kind of software, but something that makes me feel I have a modest but positive impact.

My view is that, on a daily basis, we rely a lot on software that serves the interest of a business rather than the interest of its users. Most people seem to accept the situation. I don't. My ambition is to contribute putting this situation into question by developing software that works, that is usable by everyone, and that's respectful.

I looked for ideas of software I could develop. It happened that I needed a mobile document scanning app and I couldn't find an existing one matching my criteria. So I started to develop it. Implementing a scanning app that can be used by everyone is not trivial: the main challenges are about automatic document detection, image processing and a good user interface. But, with enough motivation, it's doable by an independent developer like me. That's how FairScan was born.

It turned out that this is a market that illustrates very well the problem I described: when you install a "free" app, either you give your private data (your scans) to Big Tech, or you're exposed to ads and dark patterns that try to get your money somehow. FairScan is my attempt to change that: to contribute to raise awareness, especially among people who don't know open source, that software can be both usable and respectful.

Building an open source project doesn't have an impact that is as directly visible as, for example, teaching maths to kids. Still, FairScan is now used in conjunction with ODK Collect, an app that is used mainly by research, public health, and humanitarian organizations. I didn't expect that. I didn't think FairScan could end up contributing to efforts I actually care about.

Working on FairScan is not always easy and I still have doubts. But this is what I consider my job, at least for now. At first, I wasn't quite comfortable with the idea because it doesn't fit well with what you usually call a "job". Now, I think I am. It's the result of a deliberate choice, and it allows me to put a lot of myself in what I do every day.

Where to cut? Automatic document cropping strategies

2026-03-14T00:00:00Z

When you start a scan in FairScan and point your device to a document, the app detects the document and displays a quadrilateral on top of the image to show how it will crop it when you press the capture button. Two separate steps happen one after the other:

A machine-learning segmentation model detects which pixels of the image are part of the document.
An algorithm derives a quadrilateral from the outline (or contour) of the document pixels returned by step 1.

We don't want just any polygon, we want one with four edges, because that's what can be mapped to a digital image or to a PDF page. And that's the responsibility of step 2, which could be summarized as: "where to cut?"

There are multiple ways to do that, and they don't all lead to the same result. The difference is subtle in many cases, but in others, that are not so rare, it's impossible to miss.

Approach 1: looking for corners

I found many examples on the web that show how to code your own "document scanner" in just a few lines of code. All of them rely on the Douglas-Peucker algorithm, that was published in 1973 in the context of cartographic generalization. This algorithm simplifies a curve by removing points while ensuring that the simplified curve stays within a given distance of the original one. When applying it to the contour of the document pixels, we can check whether the resulting polygon has 4 edges: in that case, we're done.

Douglas-Peucker is a simple algorithm, it's well defined and already implemented: why look further? The problem is that it gives bad results in some cases:

Some documents have rounded corners (for example some identity cards). The algorithm then selects a point on the contour that is close to the corner but it has to "cut" a bit the edges of the document.
When a document misses a corner (folded, stapled...), it appears as having 5 edges, not 4. To have only 4 vertices, the algorithm has, again, to cut some part of the document.
When the document detection step returns a set of pixels that doesn't reflect well the reality, the algorithm may give very bad results. Among the hundreds of points in the contour, only 4 matter for the final result and any imprecision has a big impact on the resulting quadrilateral.

The algorithm works by removing points from the initial contour. By design, the four corners of the resulting quadrilateral must already exist in the original contour. The algorithm cannot create new corners, and this turns out to be a major limitation.

Approach 2: looking for edges

I looked for a different kind of algorithm, that is more adapted to identifying a document. A key intuition is that edges are long and stable parts of the contour, while corners are short and often noisy. Instead of focusing on the small corner regions, we can rely on the long straight segments that make up most of the document boundary. There are well-known mathematical ways to fit a line based on a set of points, so the main challenge is to split the points of the contour so that we can define a line for each edge.

One way to split the contour points is to look at the "orientation" of the contour at each point: we can take the previous point and the next point and draw a line between them to get a sense of the direction (the tangent) of the contour at this precise position. Points that are part of the same edge of the document should have the same orientation. Of course, there may be some imperfections in the contour so we can use a sliding window to remove slight variations.

The algorithm can then look like that:

calculate the orientation (an angle) of the contour for each one of its points
group adjacent points that have a similar orientation
select the 4 largest groups of points
fit a line for each group: each one is an edge of the quadrilateral
corners can be calculated as the intersections of adjacent edges

In this algorithm, we use much more data than when focusing on the corners: a few "bad" points are therefore less likely to impact the result.

This algorithm fixes the problems Douglas-Peucker had with missing or rounded corners: we can reconstruct corners that are not part of the original contour. It also handles cases better when the detected document pixels (the segmentation mask) are imperfect, because it can rely on partial edges to reconstruct them. That doesn't mean it can save the worst cases, but that's still quite valuable.

This new algorithm is slightly slower than Douglas-Peucker, but still very fast compared to the segmentation model itself, so the difference is not noticeable in the app.

More importantly, it produces much more reliable quadrilaterals in difficult cases such as rounded corners, folded documents, or imperfect segmentation masks. After testing it on hundreds of images, it consistently produced better results than the previous approach.

The key idea is simple: instead of trying to guess four precise corner points, the algorithm looks for the four long edges that define the document. Those edges are much more stable and carry far more information than the small, often noisy corner regions. In practice, that small change in perspective makes automatic cropping much more robust.

The new edge-based detection algorithm is now available in FairScan 1.16.0.

What's a good scan?

2026-02-15T00:00:00Z

In my previous post, I talked about failed scans, but what's a good scan? What does it look like? How is it different from a photo? It's a question that comes back regularly when I work on FairScan, and I still don't have a clear answer. What I know is that this question quietly drives many of the strategic choices I make. I recently worked on improving how FairScan handles color documents, and that was a good opportunity to reflect on it with the experience I gained over the past months.

A scan is not a photo

A photo is about capturing a scene, something that happens within a given environment, with a particular atmosphere. It's largely about light: in fact, the word photo comes from the Greek word for light. Light comes from a source, either natural (the sun) or artificial (a lamp), and it has a direction. The way light falls on a scene, the way it highlights some parts and leaves others in the dark, plays a crucial role in the impression we get when looking at a photo.

A scan, on the other hand, tries to capture a document and only that, as if it were isolated from the world, under light that is as uniform as the surface of a screen. A flatbed scanner is a good reference for that ideal.

In comparison, a phone's camera has a major advantage: it fits in your pocket and is already connected to your digital world, making it easy to share documents instantly. But being able to take a photo of a document is very different from having a scan of that document.

What we expect from a scan

When you look at a scan, you probably have expectations that you don't consciously articulate. There is likely no absolute truth here, but working on FairScan forces me to identify what I believe are the most common ones:

Homogeneous brightness: light should be uniform, shadows should be avoided
Bright enough, but not washed out: there should be enough light without losing details in the brightest areas
Readable contrast: differences in brightness are crucial for readability, especially for text
Color only if there's color: if at least one element in the document is colored, I want the scan to show it; otherwise, I expect a black-and-white scan

Ideally, I think a good scan should look like the document appeared on a screen before it was printed. Sometimes it's more complex than that: elements can be added later on paper, like stamps or handwritten annotations. But in most cases, trying to reproduce the original digital document is a simple way to define a clear goal.

As a user, I don't want to think about how to adjust a photo to get a decent scan. Which parameters should I tweak? In what order? An app like FairScan should take care of that automatically. That's how I can get a usable scan in a few seconds, without effort.

Enhancing without betraying

A document scanning application starts by cropping a photo to remove everything that is not part of the document (see this blog post). The goal is then to "enhance" the photo to make it look like a scan, but without damaging it in the process.

When you see a document as part of a photo, as one element of the physical world, your brain tends to extrapolate what the document should look like. The surprise comes after cropping: the exact same pixels that made the document look white within a photo often don't look white anymore once everything around them is removed. What appeared to be white paper is in fact frequently composed of grey pixels (see another blog post).

To mitigate this, earlier versions of FairScan processed color documents using a very basic approach: increasing the brightness of all pixels by the same factor. Unsurprisingly, the result was sometimes too dark, sometimes washed out and unreadable. FairScan 1.14 uses a more careful strategy, increasing brightness based on image content rather than an arbitrary constant.

Making brightness homogeneous is also difficult. Reducing shadows involves evaluating brightness variations across the document and compensating for them. The challenge is that two things are mixed together: the lighting that reaches the document, with its direction and intensity, and the intrinsic reflectance of the document itself, which depends on its content. On a black-and-white document, how can an algorithm distinguish a shadow from an area that was intentionally printed in gray?

How I approach this in FairScan

I didn't know anything about image processing before working on FairScan. I learn techniques as I encounter concrete problems and look for ways to solve them. To compare algorithms or parameter choices, I usually test them side by side on a small set of images that cover a wide range of situations. Before shipping, I also review the results on hundreds of images from my dataset to make sure the changes actually move FairScan closer to what I consider a "good scan".

It's also essential that the processing shipped in the app doesn't make it slower. FairScan should feel fast: when you capture an image, you expect to see the result almost immediately. This often means finding a trade-off between visual quality and performance on a mobile device. In practice, it's sometimes possible to gain significant performance with a loss in quality that very few people will notice.

So what is a good scan?

I still don't have a single, definitive answer. I believe it should be both readable and reasonably faithful to the original document, but I'm still exploring how to translate that into FairScan. Much of it comes down to product choices, especially deciding how far the app should go when it "enhances" images.

What I know for sure is that this has to remain compatible with what I'm trying to build: an app that produces PDFs that don't require manual adjustments. The work I want to spare users must be handled by FairScan itself, which means carefully engineering and fine-tuning its behavior. In the end, even if the app does a lot behind the scenes, that complexity should remain invisible. To users, FairScan should feel fast and simple. Always.

Learning from failed scans

2026-01-20T00:00:00Z

Since version 1.0, released last September, FairScan has been updated 11 times with regular improvements. Many of those updates focus on FairScan's core, the automatic processing of captured images, with the goal of producing clean PDFs effortlessly. And yet, the result is not always what you expect. The result is sometimes not as good as what you get from a commercial app, even if it's done in a much more respectful way.

Of course, what those commercial apps produce is the result of years of work. Some of them also store all user scans in the cloud, which gives them access to massive amounts of data they can use to improve their algorithms. FairScan doesn't collect any data from its users, and its detection model is trained on a public dataset.

With the latest release, however, there is now an easy way to share the images that FairScan doesn't handle well. And that can help make FairScan better.

Where the processing can fail

When you tap on the capture button in FairScan (the big round one), you get a preview of the scanned page after a fraction of a second. It's not the photo you just captured, but the result of the automatic image processing pipeline that the app runs behind the scenes. As the app is still far from perfect, each step of that pipeline can produce suboptimal results.

Here are some typical examples:

Document detection is the most critical step. It may fail to detect edges accurately, especially in difficult conditions, for example when multiple documents appear in the frame.
Color detection tries to determine automatically whether a document should be processed as grayscale or as color, but this is not always as straightforward as it sounds, particularly with low-saturation colors or under dim lighting.
Brightness and contrast are adjusted automatically, which can sometimes result in documents that are too bright or too dark.

When the app produces a good-looking document (which is hopefully most of the time), that's great for users. But those cases don't help improve FairScan. The real learning comes from the situations where the result is disappointing. Those "bad" cases highlight what needs to be improved and help guide future work.

How you can help

When a page is processed badly, you can now report it easily:

Open the menu at the top right and go to the About screen
Tap on Report a problem with last captured image

Your system will then let you choose which app to use to send the image. The email address is prefilled with contact@fairscan.org. Nothing is sent directly by FairScan: the app only prepares the data and hands it over to the app you choose to actually send it. Your email app should let you see the image before sending it, and you can add a short description of the issue you noticed.

Please note that the image that is sent is not the result of FairScan's processing. It is the raw image captured by your device, which serves as the input of the processing pipeline. Also note that tapping End scan on the export screen deletes all temporary images, including the last captured one.

What I will do with what you send (and what I won't do)

I will not share or publish your images. This is probably what you would expect from an app that aims to be respectful, but it's worth stating explicitly. Please avoid sending sensitive documents, though: I would not feel comfortable receiving them. Also keep in mind that email is not encrypted.

When you send an image, I reproduce locally the processing that happened on your device. That's why the FairScan version you used is automatically included in the email subject. It allows me to observe the issue myself and investigate it properly.

Over time, these reports help reveal patterns: situations or document types that are not well represented in the dataset I built to train the document detection model. When that happens, I do not add the received images to the dataset. Instead, I create similar images myself. This is because copyright may apply both to the photo itself and to the documents that appear in the image.

The dataset currently contains over 600 images. That's already useful, but it's still a very small sample compared to the variety of documents and real-world conditions in which FairScan is used every day. Inevitably, it has biases that need to be identified and addressed. This is especially important since the same dataset is used not only for document detection, but also to evaluate other heuristics in the processing pipeline, such as color detection (see this blog post).

With FairScan, you own your data. Your scans are not automatically uploaded to a cloud to be analyzed or reused by large companies.

If you're willing to help improve FairScan, you can now easily share an image that the app didn't process correctly. This directly helps improve the automatic processing pipeline and make its results more reliable over time.

Every report contributes to better scans, for everyone.

FairScan can now be called from other apps

2026-01-03T00:00:00Z

FairScan was designed to make document scanning very easy. It lets you decide what to do with the resulting PDF: you can store it on your device, or share it using any app installed on your phone that declares it can handle PDF files. With FairScan 1.9.0, the latest release as of today, FairScan also makes it possible for other apps to call it directly and receive a PDF in return.

Making apps cooperate

Android apps can cooperate and exchange data through a mechanism called intents. The most typical example is when an app lets you "share" some data such as a picture, a contact, or a document. The Android system then shows a list of apps that can receive it, and you choose the one you want.

An intent can also be used by an app to execute a task and get a result back, for example taking a picture or selecting a file. If several apps can handle the request, the system lets the user choose.

This same concept could apply to document scanning: apps that occasionally need a PDF could delegate the job to a specialized app. Since there are many document scanning apps, letting the user decide which one to use would make sense. However, I didn't find any standard intent for document scanning. I'm actually not aware of any scanning app that supports being called that way, either open source or closed source.

So FairScan now defines its own intent, and other apps are free to use it. Instead of reinventing a scanning feature that might not work as well as a dedicated tool, other apps can now delegate that task to FairScan and focus on what they do best.

Adapting FairScan

FairScan was initially designed as a standalone app, so I had to adapt it to ensure a smooth user experience when called by another app:

The scanning flow is simplified: no home screen, and no export screen at the end, the calling app decides when to start the scan and handles the resulting PDF.
The settings screen is disabled: FairScan currently has very few settings, and they would not make sense in that mode.
I reworked the way FairScan stores and manages captured images so that multiple processes can run concurrently and remain isolated from each other.

How it started

I wouldn't have built this feature without a message from Tenam Sobti, who not only suggested the idea but also provided a working prototype. Many thanks to Tenam! This is the kind of collaboration that make working in open source rewarding.

The initial goal was to allow the ODK Collect app to use FairScan. ODK Collect — as well as KoboCollect — is used by research teams and humanitarian organizations to gather data using customizable forms. Since these apps are flexible, they didn't need to change their code to use this feature: users can simply configure their forms to call FairScan (see this discussion).

Practical impact

Being able to call FairScan from another app is not revolutionary: users could already open FairScan, scan their document, and then import the PDF somewhere else. However, an intent-based workflow brings clear advantages:

It's much easier to use: no need to switch apps or manage PDF files manually.
It's less error-prone: no risk of selecting the wrong file when attaching a PDF.

Imagine a field worker filling a survey form offline for a research project, needing to attach a signed consent form. Instead of manually scanning it, saving it, switching apps and uploading it, the form app can now simply ask FairScan to scan the document and receive the PDF instantly.

This new FairScan feature could be useful for many types of applications: cloud storage, note-taking, document management… If you're building an app and want to try it, you'll find instructions in the FairScan repository on GitHub.

I'd love to hear about apps that make use of this feature: feel free to reach out!

A data-driven approach to color detection in FairScan

2025-12-14T00:00:00Z

FairScan's goal is to make it fast and easy for users to get a PDF. To achieve that, the app handles all image processing steps automatically. As a user, you have implicit expectations about the result. One of them is simple: if you see colors on your document, you expect a color PDF. Otherwise, you expect a grayscale one.

That sounds easy. But with FairScan 1.7, I could see myself that the app was not doing a great job at that. Some users' comments confirmed it. I needed to improve the automatic distinction between color and grayscale documents. However, if I change anything in this processing, how can I know whether what I do is actually better, or worse, than before?

Data to the rescue

There is an approach that works really well for this kind of problem: benchmarking. The idea is to use a dataset, with inputs and expected outputs, and to measure progress against it.

Getting a dataset can be a big task on its own. But I had already built a dataset to train the segmentation model, which I described in a previous post. It contains more than 600 images of over 200 different documents. It did not include information about whether documents were grayscale or in color, the so-called ground truth, but that was something I could complete in less than one hour.

I also had to write a small script to compute a score for the current implementation. Again, that did not take long. Here is the initial result.

Initial score:

Number of images: 652
Accuracy: 86.7%
Expected color is true and detected color is false: 38 images
Expected color is false and detected color is true: 49 images

What matters most is that getting this score is easy and fast: one click and about one minute on my computer. I could certainly make it faster, but it is already good enough to iterate quickly.

First improvement

The algorithm used in FairScan 1.7 to detect colors is simple. It counts pixels above a given chroma threshold, which measures colorfulness, and compares the proportion of such pixels against another threshold.

I had already identified one low-hanging fruit. Instead of considering all pixels inside the quadrilateral of the detected document, the algorithm should exclude pixels that are not part of the document according to the segmentation model. This may look like a subtle change, but it improves all cases where the document appears slightly concave, which is very common, or where a corner is missing because it is torn or stapled.

This change was easy to implement, and the score immediately improved to 90.6%.

Overall strategy

Improving the score is a good start, but it is still far from 100%. That does not mean the change was not useful, but it clearly means more work is needed. So what is the strategy to approach the problem?

Here is the process I follow:

Build a benchmark
Look at individual failed cases to understand why the score is low
Find a way to improve some of these cases
Validate the change against the benchmark
Iterate, going back to step 2

At this point, one improvement was validated. It was time to iterate.

Iterating

When looking at documents incorrectly detected as colored, it quickly became clear that many cases were related to lighting conditions. A black-and-white document photographed under dim light often appears slightly blue. With artificial light, it can appear slightly yellow or even reddish.

One possible workaround is to apply a white balance algorithm, such as the grey world assumption. I first applied it to the whole image and checked the benchmark. The score dropped. In other words, validation failed.

Looking at the new incorrect cases revealed a clear pattern. When the background was strongly colored, for example a red sofa taking most of the frame, the grey world algorithm compensated for it and made the document turn slightly blue. That was clearly not what I wanted.

The fix was to apply the white balance algorithm only to the document area. This time, the benchmark score increased to 91.7%. Validation succeeded, and the iteration could continue.

For color detection, FairScan relies on the CIELAB color space, which was designed to better match human perception than RGB. One interesting observation is that many pixels in a document are either very dark or very bright. For such pixels, humans barely perceive any color. I therefore tried filtering out pixels with very low or very high luminance, the L component in CIELAB. This resulted in a small improvement, bringing accuracy to 91.9%.

When inspecting chroma heat maps for incorrectly processed grayscale documents, I noticed that chroma values were sometimes high near the edges of the document. This is explained by the fact that the segmentation mask is not perfect, and some background pixels are incorrectly included. Because the proportion threshold for colored pixels must be low to detect documents with only small colored areas, these few pixels can lead to false positives.

The fix here was straightforward. I removed a small number of pixels along the border of the detected document. Not too many, so that documents that are only colored on the border can still be detected correctly. With this change, the score rose to 94.3%.

Parameters

At the end of each iteration, I adjusted the algorithm parameters to maximize the benchmark score. The main parameters are the chroma threshold and the proportion threshold for colored pixels. Changing them is similar to moving a cursor that favors either color or grayscale detection.

A different dataset would likely lead to slightly different values. However, I believe these values would not change significantly with another dataset that has a good variety of images.

The end of it

After implementing several improvements, I did not reach 100% accuracy. When I look at the remaining incorrect cases, I think some of them are still reachable, but I am running out of ideas that would improve them without lowering the overall score.

The last few percent are clearly harder to get and are probably not where I should focus right now. For now, I decided to stop here. I know with confidence that FairScan 1.8.0 performs better than all previous versions.

The automatic distinction between color and grayscale documents is probably the part of FairScan that fits best with a benchmark-driven approach. The expected result is binary, color or grayscale, which makes it easy to evaluate and quantify.

This kind of benchmarking is also especially useful when the goal is to match human perception. Detecting whether a document should be considered colored sounds trivial, but it is not. A benchmark helps validate, or invalidate, that a given change is a real improvement. I will definitely rely on this approach again for other steps of FairScan's automatic processing, so that users can get good-looking PDFs in most cases by doing nothing more than clicking a button.

Creating an open source app for everyone: it takes more than code

2025-12-03T00:00:00Z

My ambition with FairScan is not just to build an open-source app: it's to make an app that everyone can use, including all the people who don't know what GitHub is. That's definitely not easy and it takes more than writing good code. Before starting FairScan, I already knew there was a big difference between good software and a good product. Now, I experience it very concretely. This is my daily reality.

It takes a good UI so that it's usable by everyone

Open source apps are started and built by developers like me, but what users see is the user interface (UI), not code. The UI of an app should enable people to use it without reading documentation, and that's not trivial. I'm not a user experience (UX) designer. No UX designer worked on FairScan, and I believe that's the case for most open source apps.

So I designed FairScan's UI myself and I make it evolve. Being aware of my limits, I tried to learn. I read Steve Krug's book, Don't Make Me Think, and it helped a lot when non-technical testers started using FairScan. Google required me to have 12 testers try the app before I could publish it on the Play Store. They were not next to me and had to figure out the app on their own. That was a revealing moment: several of them did not understand the basic workflow of the app. I had to rethink the UI and change significant parts of it. Once I did that, it became much easier for testers to understand how they could use the app. Now that some users tell me they appreciate "how easy it is to use", I'm convinced it was worth the effort.

Making the UI usable for everyone is a big step, but it still leaves open a deeper question: what should the app actually do?

It takes a product strategy to define where the app should go

The UI is crucial to expose the app's features, but which features? And among those features, which ones actually matter? Among all the things that could be improved in the app, what should development focus on? Those are exactly the questions that a product strategy tries to address. In a product development team, that's the job of product managers, who are maybe as rare in open source projects as UX designers. I knew almost nothing about product management before I joined a "product-first" company. There, the CEO had no problem saying "no" to customer requests. At first, that was a bit of a shock to me. Over time, I realized that a product is the result of choices, and avoiding choices makes the project lose direction. The product vision, and the strategy derived from it, help make conscious decisions, and that's what turns an app into an intentional system rather than a loose collection of features added whenever someone happened to request them.

All of that stayed with me, and it shaped how I approached FairScan from day one. What I wanted to achieve was already fairly clear early in the project: the "simple and respectful" approach that I described in my first blog post. And shortly after that came the first requests from users. It's open source, so they're not customers, but just like customers, users ask for specific new features. And as the developer, it's uncomfortable to push back: if I want to have users, shouldn't I say "yes"? The problem is that each new feature has a cost, not only technical (implementation and maintenance) but also functional because it becomes harder to keep the app consistent. More importantly, the requested features don't always align with the long-term vision.

The typical example for FairScan is that some users want to manually adjust the detected document edges. In my view, improving the precision of the automatic document detection is the alternative that's aligned with what I want FairScan to be. The product strategy helps make such decisions. It clarifies priorities based on long-term user value, not on what looks like the easy short-term path. It's what makes it possible to invest in hard but impactful improvements. It provides a direction, and without a direction, an open source project can drift very quickly.

A clear vision helps keep the app on track, but turning that vision into something that works in practice is another story.

It takes time and effort, a lot

I doubt it's possible to come up with an app that "just works" for everyone without putting a lot of effort into polishing every aspect of it. The UI is definitely part of that, but user experience goes far beyond the interface. For FairScan, I already spent a lot of time improving how the app behaves when multiple documents are in the frame, or when a document missing a corner seems to have 5 edges instead of 4. Because I want FairScan to rely on automation to make things easy for users, I know it's a neverending story, and I'm fine with it.

And beyond that, like any other app, there are countless details that don't show up immediately but still matter: how the app behaves in unexpected error cases, how it deals with different Android versions, how persistent state transitions when upgrading the app… Those are the things that make the difference between an app that works and an app that is truly reliable. All of that takes time and dedication. And it's not always fun. A developer who is paid to work on an app understands that it's part of the job. But it's not quite the same thing to work on similar tasks for an open source project in your free time. Users don't explicitely ask for any of it so there's no immediate reward. But attention to these details can bring more users over time, and that's a kind of long-term reward.

All these aspects add up. And building an open-source app for a broad audience is definitely challenging. It requires great care for user experience, a solid product vision and a lot of hidden work that nobody asks for directly. But that's also what makes it meaningful. I know FairScan won’t fit everyone’s tastes, but my hope is that anyone can use it. And maybe one day, through FairScan, some people will realize that open-source exists. And maybe they'll raise their expectations about how respectful the software they use daily should be. That would be my biggest success.

Building a public dataset for FairScan

2025-11-14T00:00:00Z

To automatically detect documents, FairScan uses an image segmentation model. The dataset needs to reflect the situations the model should be able to handle, so the model's accuracy depends heavily on the quality and size of that data. For FairScan, I decided to build a dedicated dataset and to make it public. That turned out to be quite an experience.

Why building a public dataset?

Before starting, I looked for existing datasets. I found datasets for OCR or for unwarping documents. I also found a dataset for document scanning, but it was focused on videos and only included a few documents. I could not find anything that matched what I needed, so I had to build it myself.

I could have built a private dataset, but I did not seriously consider that option. FairScan is an open source app and the spirit of open source development is to make it possible for other people to understand how an application works and to modify it. For a model, the training data is at least as important as the source code. Publishing the code without publishing the dataset would have made little sense, especially for an app that aims to be respectful. It was clear to me I had to build a public dataset.

What the dataset contains

A dataset should contain examples of what the model is expected to produce for given inputs. For an image segmentation model that should detect documents, the input is an image and the expected output is a mask that shows which pixels correspond to a document. Here is an example:

To make the model reliable, the dataset needs to cover the situations in which people use a scanning app:

Various types of documents, for example standalone sheets, books and magazines
Various supports and backgrounds, for example a busy desk, a kitchen table or a carpet
Various framing and perspectives, for example close, far or low angle
Various lighting conditions, for example bright sunlight or a dim lamp

Generally speaking, models perform better when they have more data, including some difficult examples, such as a white document on a white background. For an early development version of the app, I started with a dataset of 100 images. As of today, FairScan's dataset contains more than 600 images. My family often saw me taking pictures of documents in strange situations, for example in dim light on the white background of the bathroom sink.

Annotating images

Taking pictures is only one part of the job. The other part is to annotate them, which means defining the expected output for each image. Among the multiple tools that exist for that purpose, I used labelme. It allows you to draw polygons directly on the image to create segmentation masks. For a simple sheet of paper lying very flat, it can be quick. For the curved page of a book, approximating the shape with a polygon can require many clicks. Since the model's precision depends on the precision of the dataset, I did this carefully, using the zoom to place polygon vertices as close as possible to the visible contours. It is certainly tedious, but it was not the only time-consuming task.

Documents for a public dataset

One problem I faced is that I cannot take pictures of any document and put them in a public dataset. That may lead to copyright issues. I take that seriously, especially since I want FairScan to be respectful not only of its users but also of other people's work.

Some documents can be used without any issue. That includes everything that is in the public domain, and Wikimedia Commons has many such documents. I believe that forms issued by public administrations are also acceptable. I added photos of documents that I created in the past, or that were created by people I know who agreed to that usage. That was a start, but it was not enough to represent the variety of documents people scan. Think of books, magazines or color prints.

So I created additional documents myself. I took inspiration from layouts I found at home or online, and recreated documents with dummy content such as Lorem ipsum or with photos from Unsplash, which is allowed by their licence. I created business cards, flyers and textbook pages that I inserted into real books. They only need to look like real documents:

Avoiding overfitting

Creating documents takes time, so the temptation is to reuse them in many images. However, this creates a risk of overfitting. If the dataset contains many images of the same document, the model may learn to recognize that specific document instead of learning what a document looks like in general. I tried to limit the dataset to a maximum of 5 images per document. To reach more than 600 images, I still needed over 120 different documents.

Looking back at the process, building a public dataset clearly takes a significant amount of work. Life is easier for companies that train models without disclosing the training data. They can afford to be less careful with copyright and they can outsource the annotation to low-paid workers who label data all day long. That's how the AI economy works. I chose a different path and I have no regret. Yes, it required effort, but I feel a real satisfaction in knowing that this dataset forms the foundation of FairScan. It is fully aligned with the goal of building a respectful app, and FairScan is a small demonstration that this approach is possible.

Making document detection more reliable

2025-11-12T00:00:00Z

I released the first public version of FairScan about two months ago. It aims to be very simple, so that one can get a PDF in just a few seconds. To achieve that, the app relies heavily on automatic processing... but that's easier said than done. The very first review I got on the Play Store read something like: It doesn't work, "no document detected" on every page. Not exactly what I had hoped, but a good reminder that automatic document detection isn't just one feature among others: it's the feature that can make or break the whole experience. If detection fails, the app fails.

When releasing FairScan, the system seemed good enough, but I knew it wasn't perfect. Some cases were particularly difficult:

Certain document types, such as textbooks or magazines
Images containing multiple documents
Documents with a missing corner, folded, or stapled

In those situations, the app often displayed "No document detected". If that happens on every page, there's only one conclusion: the app doesn't work. I had to do something.

Improving FairScan's segmentation model

In a previous article, I explained FairScan's image processing pipeline, how it turns a photo into the image that ends up in a PDF. The very first step is the segmentation model: detecting which pixels in the photo belong to the document.

That can be tricky when there's more than one document in the image. The pixels of one document look just like those of another, so the model may treat them as one big blob, either producing a strange merged shape or failing to detect any quadrilateral at all. From the start, I worked around that limitation by training my segmentation model to identify only the main document in an image. It worked in many cases, but not always.

To improve this, I tried an instance segmentation model (YOLO 11). Unlike a semantic segmentation model such as DeepLabV3+, instance segmentation can distinguish several separate documents within the same image. I knew it would be more complex to integrate, but I also knew it could handle those situations better.

To train it properly, I had to revisit my dataset and annotate every secondary document visible in the images. That raised an interesting question: what counts as a "document"? If only half a document appears, does it qualify? What about a tiny corner, or a blank page? Those choices could affect the model's behavior, so I removed ambiguous images entirely. From roughly 400 images, I went down to about 300.

I trained the YOLO model on this dataset, and the results were promising, but it was clear I needed a larger dataset. So I added new types of documents that were underrepresented, such as textbooks and magazines. That took time (as I describe in another post), but with around 600 images, both the semantic and instance segmentation models improved noticeably. The new models perform better across document types and handle multiple documents more reliably. Still, the instance segmentation model wasn't consistently better at separating documents, and integrating it into the Android app would have required substantial work. For now, I've chosen to keep the simpler semantic segmentation model in production.

Making the system more robust to non-quadrilateral documents

The segmentation model is crucial, but it's not the whole story. From its output, the app must derive a quadrilateral that can be mapped to the final rectangular image. But what if a document is stapled, folded, or missing a corner? Then the segmentation output might be a polygon with 5 sides, not 4. And if the app can't handle that, the user gets another "No document detected".

I tried training a regression model to predict a quadrilateral from the segmentation mask. In theory, that could handle missing corners or imperfect masks. I extended my dataset with "expected" quadrilaterals and trained the model accordingly. The results were mixed: not bad, but not good enough. Excluding poor segmentation cases didn't help much either. After several attempts, I realized I was overcomplicating the problem and decided to move on.

I switched back to more traditional image processing and designed new fallback algorithms that activate when the default detection fails. Some of the algorithms I tried are not well-known techniques. They're just my ideas for the particular problem I have to solve. One is purely geometrical: when the detected polygon has more than 4 sides, it searches for 3 consecutive angles that are almost right angles and builds a quadrilateral from them. Another, more basic one simply constructs a quadrilateral around the detected contour: it's not ideal, but less frustrating than getting an error message.

The dreadful "No document detected" should now be much rarer. Over the past few weeks, I've explored several approaches: some worked, some didn't, but all contributed to a better understanding of the problem. Expanding the dataset and adding new fallback algorithms made FairScan significantly better at detecting documents of all kinds. It's still not perfect, but it's definitely one big step closer. Try it and see for yourself.

What's a respectful app?

2025-10-02T00:00:00Z

I often describe FairScan as simple and respectful. But what does "respectful" really mean when we talk about apps? We live in a world where there’s an app for everything, and we’re constantly pushed to install more. Yet almost no one talks about "respectful apps". A quick search online gives barely a few hundred results. In other words: it’s not even a topic. So let me explain what I mean when I use that word.

Disrespectful behaviors in mobile apps

Before working on FairScan, I tried quite a few Android apps for scanning documents. And all of them exhibited behaviors that I certainly don't want.

Some of those behaviors are intended to be very visible: ads of all kinds, but also messages to upgrade to a premium version of the app. In some apps, such messages take up the whole screen.

Some others are hidden, almost invisible to users. Trackers are the best example: most users don't know about them, but some apps have dozens of trackers, and they collect massive amounts of data about us and send it to data brokers and Big Tech.

Most often, it's in between. For example when the app notifies you in small characters that all your scans are stored in their cloud: you have no choice but to give them your private data. Or when the app stops working after you scanned 3 documents unless you buy the paid version. Welcome to the world of dark patterns.

As a user, I would expect my apps to not have those behaviors. Or, at least, to be able to disable them. When we talk about relations between humans, we have words for that: manipulation, concealment, unfair pressure... All are considered disrespectful. Why would it be different with an app? What would make it more acceptable?

Whose interest is it about?

If those behaviors are against the interest of users, why do they exist? That's because they serve the interest of someone else: the app's publisher, sometimes referred to as "developer" but the people who develop an application write code that their employer asks for.

Who develops and publishes applications? It can be individual developers or various kinds of organizations or public institutions. But the most well-known applications are developed by companies, small or big. And we get to know those applications because the companies that produce them have marketing budgets to serve their business goals.

In the end, the way an app behaves reflects a conflict: the user wants an app that does a given task without hassle, while the company producing the app just wants profit. Most companies that distribute a "free" app do it to make money through ads or to lure users into buying a premium version. Big tech companies, on the other hand, are more interested in getting user data ("If you’re not paying for the product, then you are the product"). It doesn't make a big difference in the end: those disrespectful behaviors exist only to serve the business goals of those companies.

How can we know? What can we do?

What can we do about that as users? The first thing is to think twice before installing an app, maybe we don't really need an app for everything in our lives. You can:

Get information about who's producing the app and what their business model is
Check the permissions that the app requires and the trackers included in the app
Read the privacy policy and the license (when it exists) even if it's often a boring and cryptic read
Check whether the app is open source

The fact that an application is open source doesn't make it automatically respectful but it's probably the best guarantee you can get: if it contains disrespectful code, someone can remove that code and republish the application.

You may also consider paid apps: it gives the company a clear way to get money from the app, although it certainly doesn’t guarantee respectful behavior.

To sum up, a respectful app is one that puts the user’s interest first, without tricks or hidden agendas. I wish we saw as much creativity in building those apps as we see in inventing new dark patterns. I hope FairScan can be an example of an app that does its job well and respects its users.

The Heart of FairScan: the image processing pipeline explained

2025-09-30T00:00:00Z

How does FairScan work at its core? How does it transform an image captured by the phone's camera into the page of a PDF document that doesn’t just look like a photo? From the user’s point of view, it feels like a single transformation that happens in less than a second. Let’s look at the different steps involved, illustrated with a visual example.

Segmentation

The first step is image segmentation, which identifies the pixels that belong to a document. I trained a custom model specifically for images containing documents.

Here you can see the original image combined with the segmentation mask (the green overlay) produced by the model. Since the model was trained to identify only one "document" even if multiple are visible, you can see that only part of the second document in the picture is captured.

This is the most crucial step, the one that can feel a bit “magical.” I plan to keep improving the model so it detects documents more reliably in all kinds of conditions.

Contours

The next step is to detect the edges of the document based on the segmentation output. Edge detection is a well-known problem in image processing, and the Canny algorithm is widely used for this task.

In my first attempt at FairScan, I skipped segmentation and ran Canny directly on the captured image. That worked in some cases, but segmentation produces much better results when the background and the document have similar colors or when shadows are strong.

Quadrilateral

At this stage, the assumption is that documents are rectangles. So we want to identify a quadrilateral. Your brain probably sees the document on the photo as a rectangle, but because of perspective distortion, it isn’t. The previous step may return several contours of arbitrary shapes. We approximate these contours as polygons using the Ramer–Douglas–Peucker algorithm, then filter out those that don’t have 4 edges, and finally pick the one with the largest area.

Perspective correction

The next step is to correct the perspective and crop the image. This involves applying a perspective transformation based on the quadrilateral from the previous step and mapping it to a target rectangle.

The most important part here is the aspect ratio so that the document doesn’t look distorted. For now, I use a simple heuristic based on the average of opposite edges. It gives acceptable results as long as the photo wasn’t taken from too oblique an angle.

Post-processing

Maybe you’re thinking: “the image on the left has a strange color.” That really is the color from the original photo (I promise). I guess that when looking at the photo of a document, the human brain tends to interpret the main color of the page as white, especially because it contrasts with the darker background. But it’s not actually white, and you don’t want your PDF to look like that.

So the last step adjusts parameters like brightness and contrast to bring the result closer to what you expect from a digital document.

This step struggles in low-light conditions and doesn’t always correctly identify when a document should be treated as grayscale. There’s definitely room for improvement here.

That's it: all of those steps make the heart of FairScan and it all happens very quickly. In fact, the first steps already run live on the camera preview to display the quadrilateral, so the user immediately sees what FairScan detects as the document.

This pipeline combines several steps, most of them relying on well-established algorithms implemented in open-source libraries. Before starting this project, I knew nothing about image processing. It took me quite some time to tune this pipeline, but I learned a lot along the way. And I know each of these steps can still be improved to automatically produce cleaner PDFs. From the user’s perspective, it will continue to feel effortless.

FairScan's purpose

2025-09-28T00:00:00Z

I just published the first version of FairScan and I'm starting this blog to share my experience developing this project. This first post is about the vision behind FairScan: what I'm trying to achieve, and what I'm not aiming for.

I started FairScan to fill a need I have, and one that many people share: every now and then I have to turn a piece of paper into a PDF. Of course, there are many apps that do this, and a lot of them are free. But "free" often means I end up paying in other ways, by giving away my data or being exposed to ads. And most of these apps are bloated with features I don't need.

FairScan is my attempt to build something different: simple (getting a PDF in seconds, without effort) and respectful (no ads, no account, no tricks). It doesn't try to do everything, but it focuses on doing its job well.

A simple app to get a scan in seconds

I don't want to spend time using a document scanning app: I want to get a PDF quickly (around 10 seconds for a single page) and without effort. That's what I mean by "simple".

Automatic processing

I want to use my phone as a camera, but instead of a raw photo of a document, I want a PDF that looks good enough to share. FairScan takes care of the tedious work for me:

Detect document edges
Fix perspective
Enhance colors, brightness and contrast
Reduce shadows
Compress the PDF to keep it light

FairScan does all this automatically. Results may not be perfect in every case, but the goal is to get PDFs that look "good enough" most of the time, with zero effort from the user. Achieving that is far from simple for the developer, but it makes the experience truly simple for the user.

Clear interface and scanning process

Of course, the user interface also plays a key role in keeping the app simple. Automation makes it possible to remove buttons for tweaking documents, which keeps the UI clean. And since there are no ads or messages pushing you to upgrade to a premium version, there's no wasted space or distraction.

The scanning process itself is designed to be crystal clear, even for multi-page documents:

Scan the pages
Preview the result
Save or share the PDF

The result is an interface and workflow that stay focused on one thing: getting a PDF quickly and without distraction.

An app that respects its users

I would like all the apps I use to be respectful. I'll try to define more generally what a "respectful app" means in a dedicated post. In short, I think it's about putting users' interests first. In the context of a document scanner, it's really about what I don't want to have.

No account, no cloud. Big companies happily offer to store my scans on their cloud. But some of the documents I scan are definitely private data and I don't want to give that to Big Tech. I want to keep control of my data.

No ads. Ads have much more impact that most people realize, they shape how we behave individually and as a society. Plus, they're annoying. I hate ads.

No trackers. Almost all apps include trackers, but I don't want to be tracked. Check your apps.

No weird permission. I don't get why a scanning app would need dozens of permissions. I don't want it to access my location or to record audio with my phone.

No artificial limitations of any kind. I tried many "free" scanning apps. Sometimes, I got a message saying that I need the premium version to scan more than 3 pages. In another app, the PDF I got had "Scanned with FreeApp" on every page. In yet another one, I could share the PDF only if it was by email.

All of that is code that was intentionally added to the app. So, if an app is open-source, it's usually easy for someone to remove that kind of code and publish a similar app. That makes open-source apps much more likely to be respectful.

FairScan is open-source: you can review its code and check that it's as respectful as it should.

What FairScan is not

In addition to the "anti-features" I just listed, there are features that I see in a lot of document scanning apps, and that I think I don't want for FairScan. I believe it can be helpful to list them to clarify FairScan's scope.

Not a storage app

FairScan is not about storing documents and keeping them safe. I don't want FairScan to take that responsibility. FairScan keeps data only for the current document being scanned. At the end of the scanning process, the user exports a PDF by storing it in the device's Download directory or by sharing it with any app installed on the device. After a click on "End Scan", FairScan deletes the images it captured. It's then up to the user to keep the PDF safe.

Not an app to tweak PDFs

If FairScan gets adopted by many people, some will probably ask for options to adjust the page contrast or the PDF compression level. But that's not the direction I want to take. Once you open the door to manual tweaks, where do you stop? It goes against the idea of a simple app. More importantly, I believe it would discourage feedback and progress on automatic processing. Instead, I'd much rather invest development time in making the automatic pipeline smarter, so that everyone gets better PDFs without extra effort. That's the choice I make for FairScan.

That's the idea behind FairScan: a document scanner that is simple, respectful, and focused on doing its job well. It's already available on the Play Store and F-Droid, and I'm committed to improving it while keeping true to this vision. I hope this post helps explain why FairScan exists and what I'm trying to achieve, and I look forward to sharing more about the project and its context here on the blog.