Complete Update of the Model Card

README.md

@@ -1,30 +1,271 @@
 ---
-tags:
+tags: 
+- keras
 - image-to-image
+- pixelwise-segmentation
+datasets:
+- DIBCO
+- H-DIBCO
 license: apache-2.0
 ---
-# About `sbb_binarization`
 
-This is a CNN model for document image binarization. It can be 
-used to convert all pixels in a color or grayscale document image 
-to only black or white pixels. The main aim is to improve the 
-contrast between foreground (text) and background (paper) for 
-purposes of OCR. The model is based on a `ResNet50-Unet` model.
 
-For further details, have a look at [sbb_binarization](https://github.com/qurator-spk/sbb_binarization) on GitHub.
 
-# Results
-In the *DocEng’2021 Time-Quality Binarization Competition* 
-([paper](https://dib.cin.ufpe.br/docs/DocEng21_bin_competition_report.pdf)), 
-the model ranked 12 times under the top 8 of 63 methods, winning 2 tasks.
+
+
+
+# Model Card for sbb_binarization
+
+<!-- Provide a quick summary of what the model is/does. [Optional] -->
+This is a pixelwise segmentation model for document image binarization. The model is a CNN encoder-decoder model (Resnet50-Unet). It can be used to convert all pixels in a color or grayscale document image to only black or white pixels. The main aim is to improve the contrast between foreground (text) and background (paper) for purposes of OCR.
+
+
+
+
+#  Table of Contents
+
+- [Model Card for sbb_binarization](#model-card-for-sbb_binarization)
+- [Table of Contents](#table-of-contents)
+- [Model Details](#model-details)
+  - [Model Description](#model-description)
+- [Uses](#uses)
+  - [Direct Use](#direct-use)
+  - [Downstream Use [Optional]](#downstream-use-optional)
+  - [Out-of-Scope Use](#out-of-scope-use)
+- [Bias, Risks, and Limitations](#bias-risks-and-limitations)
+  - [Recommendations](#recommendations)
+- [Training Details](#training-details)
+  - [Training Data](#training-data)
+  - [Training Procedure](#training-procedure)
+    - [Preprocessing](#preprocessing)
+    - [Speeds, Sizes, Times](#speeds-sizes-times)
+- [Evaluation](#evaluation)
+  - [Testing Data, Factors & Metrics](#testing-data-factors--metrics)
+    - [Testing Data](#testing-data)
+    - [Factors](#factors)
+    - [Metrics](#metrics)
+  - [Results](#results)
+- [Model Examination](#model-examination)
+- [Environmental Impact](#environmental-impact)
+- [Technical Specifications [optional]](#technical-specifications-optional)
+  - [Model Architecture and Objective](#model-architecture-and-objective)
+  - [Compute Infrastructure](#compute-infrastructure)
+    - [Hardware](#hardware)
+    - [Software](#software)
+- [Citation](#citation)
+- [Glossary [optional]](#glossary-optional)
+- [More Information [optional]](#more-information-optional)
+- [Model Card Authors [optional]](#model-card-authors-optional)
+- [Model Card Contact](#model-card-contact)
+- [How to Get Started with the Model](#how-to-get-started-with-the-model)
+
+
+# Model Details
+
+## Model Description
+
+<!-- Provide a longer summary of what this model is/does. -->
+Document image binarization is one of the main pre-processing steps for text recognition in document image analysis. Noise, faint characters, bad scanning conditions, uneven light exposure or paper aging can cause artifacts that negatively impact text recognition algorithms. The task of binarization is to segment the foreground (text) from these degradations in order to improve optical character recognition (OCR) results. Convolutional neural networks (CNNs) are one popular method for binarization, and the sbb_binarization model is one of the. We have applied a CNN encoder-decoder model architecture.
+
+- **Developed by:** [Vahid Rezanezhad](https://huggingface.co/vahid-nejad)
+- **Shared by [Optional]:** [Staatsbibliothek zu Berlin / Berlin State Library] (https://huggingface.co/SBB)
+- **Model type:** Neural Network
+- **Language(s) (NLP):** Irrelevant; works on all languages
+- **License:** apache-2.0
+- **Parent Model:** [ResNet-50, see the paper by Zhang et al](https://arxiv.org/abs/1512.03385)
+- **Resources for more information:** More information needed
+    - [GitHub Repo](https://github.com/qurator-spk/sbb_binarization)
+    - Associated Paper 1 [Time-Quality Binarization Competition] (https://dib.cin.ufpe.br/docs/DocEng21_bin_competition_report.pdf)
+	- Associated Paper 2 [Time-Quality Document Image Binarization] (https://dib.cin.ufpe.br/docs/papers/ICDAR2021-TQDIB_final_published.pdf)
+
+# Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+Document image binarization is the main use case of this model. The architecture of this model alongside with training techniques like model weights ensembling can reach or outperform state-of-the-art results on standard Document Binarization Competition (DIBCO) datasets in the both machine-printed and handwritten documents.
+
+
+
+## Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+
+The intended use is limited to the binarization of images of historical documents, understood as one of the main pre-processing steps necessary for text recognition.
+
+
+## Downstream Use [Optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
  
-In the *ICDAR 2021 Competition on Time-Quality Document Image 
-Binarization* ([paper](https://dib.cin.ufpe.br/docs/papers/ICDAR2021-TQDIB_final_published.pdf)), 
-the model ranked 2 times under the top 20 of 61 methods, winning 1 task.
+A possible downstream use of this model might lie with the binarization of illustrative elements contained in document images such as digitized newspapers, magazines or books. In such cases, binarization might support analysis of creator attribution, artistic style (e.g., in line drawings), or analysis of image similarity. Furthermore, the model can be used / be trained for any other image enhancement use cases too.
+
+
+## Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+
+This model does NOT perform any optical character recognition (OCR).
+
+
+# Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+The aim of the development of this model was to improve document image binarization as a necessary pre-processing step. Since the content of the document images is not touched, ethical challenges cannot be identified. The endeavour of developing the model was not undertaken for profit; though a product based on this model might be developed in the future, it will be openly accessible without any commercial interest. 
+This algorithm performs a pixelwise segmentation which is done in patches. Therefore, one limitation of this model is that it is unable to capture and see long range dependencies.
+
+
+## Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+The application of machine learning models to convert a document image into a binary output is a process which can still be improved. New model structures like Transformers or Hybrid CNN-Transformers may be applied. The transformers would support the model in capturing long range dependencies in image patches. Alongside with a CNN which increases the input features, this could improve image enhancement performance. In addition, we have used many pseudo-labeled images to train our model, so any improvement or ground truth extension would probably lead to better results.
+
+
+# Training Details
+
+## Training Data
+
+<!-- This should link to a Data Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+The dataset used for training is a combination of training sets from previous [DIBCO](https://dib.cin.ufpe.br/#!/datasets) binarization competitions alongside with the [Palm Leaf dataset](https://ieeexplore.ieee.org/abstract/document/7814130) and the Persian Heritage Image Binarization Competetion [PHIBC](https://arxiv.org/abs/1306.6263) dataset, with additional pseudo-labeled images from the Berlin State Library (SBB; datasets to be published). Furthermore, a dataset for very dark or very bright images has been produced for training.
+
+
+## Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+We have used a batch size of 8 with learning rate of 1e − 4 for 20 epochs. A soft dice is applied as loss function. In the training we have taken advantage of dataset augmentation. The augmentation includes flip, scaling and blurring. The best model weights are chosen based on some problematic documents from the SBB dataset. The final model results out of the ensemble of best weights.
+
+
+### Preprocessing
+In order to use this model for binarization no preprocessing is needed for input image. 
+### Speeds, Sizes, Times
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+More information needed
+
+### Training hyperparameters
+
+In the training process the hyperparameters were patch size, learning rate, number of epochs and depth of encoder part.
+
+### Training results
+
+See the two papers listed below in the evaluation section.
+
+
+
+# Evaluation
+In the DocEng’2021 [Time-Quality Binarization Competition] (https://dib.cin.ufpe.br/docs/DocEng21_bin_competition_report.pdf), the model ranked twelve times under the top 8 of 63 methods, winning 2 tasks.
+
+In the ICDAR 2021 Competition on [Time-Quality Document Image Binarization] (https://dib.cin.ufpe.br/docs/papers/ICDAR2021-TQDIB_final_published.pdf), the model ranked two times under the top 20 of 61 methods, winning 1 task.
+
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+## Testing Data, Factors & Metrics
+
+### Testing Data
+
+<!-- This should link to a Data Card if possible. -->
+
+The testing data are the ones used in the [Time-Quality Binarization Competition](https://dib.cin.ufpe.br/docs/DocEng21_bin_competition_report.pdf) and listed in the paper on [Time-Quality Document Image Binarization](https://dib.cin.ufpe.br/docs/papers/ICDAR2021-TQDIB_final_published.pdf)
+
+
+### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+More information needed
+
+### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+The model has been evaluated both based on OCR and pixelwise segmentation results. The metrics which have been used in the case of visual evaluation are pixel proportion error and Cohen's Kappa value, and Levenshtein distance error in the case of OCR. 
+
+## Results 
+
+See the two papers listed above in the evaluation section.
+
+# Model Examination
+
+More information needed
+
+# Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** More information needed
+- **Hours used:** More information needed
+- **Cloud Provider:** More information needed
+- **Compute Region:** More information needed
+- **Carbon Emitted:** More information needed
+
+# Technical Specifications [optional]
+
+## Model Architecture and Objective
+
+The proposed model is a CNN encoder-decoder model. The encoder part consists of a ResNet-50 model. The ResNet-50 includes convolutional neural networks and is responsible for extracting as many features as possible from the input image. After that the input image goes through the CNN part, then the output undergoes upsampling convolutional layers until the same output size as image input is rebuilt.
+
+## Compute Infrastructure
+
+More information needed
+
+### Hardware
+
+More information needed
+
+### Software
+
+More information needed
+
+# Citation
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+More information needed
+
+**APA:**
+
+More information needed
+
+# Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+More information needed
+
+# More Information [optional]
+
+More information needed
+
+# Model Card Authors [optional]
+
+<!-- This section provides another layer of transparency and accountability. Whose views is this model card representing? How many voices were included in its construction? Etc. -->
+
+[Vahid Rezanezhad](https://huggingface.co/vahid-nejad), [Clemens Neudecker](https://huggingface.co/cneud), [Konstantin Baierer](konstanting.baierer@sbb.spk-berlin.de)
+
+# Model Card Contact
+
+Questions and comments about the model can be directed to Clemens Neudecker at clemens.neudecker@sbb.spk-berlin.de, questions and comments about the model card can be directed to Jörg Lehmann at joerg.lehmann@sbb.spk-berlin.de
+
+# How to Get Started with the Model
+
+Use the code below to get started with the model.
 
-# Weights
-We provide a `saved model` for Tensorflow2.
+sbb_binarize \
+  -m <from_pretrained_keras(&#34;sbb_binarization&#34;)> \
+  <input image> \
+  <output image>
 
-| Model | Downloads
-| -------------| ------------------------
-| `2021_03_09` | [`saved_model`](https://huggingface.co/SBB/sbb_binarization/tree/main/saved_model)
+<details>
+How to get started with this model is explained in the Read Me-file of the GitHub repository [over here](https://github.com/qurator-spk/sbb_binarization).
+</details>