Skip to content

Commit d856d45

Browse files
committed
added general info to the README.md
1 parent 9a735e2 commit d856d45

File tree

2 files changed

+53
-6
lines changed

2 files changed

+53
-6
lines changed

DR4DNA-impl.svg

+4
Loading

README.md

+49-6
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Python 3.
2020
# Installation
2121

2222
```
23-
git clone [email protected]:thejanky/DR4DNA.git --recurse-submodules
23+
git clone [email protected]:umr-ds/DR4DNA.git --recurse-submodules
2424
cd DR4DNA
2525
2626
# optional: create a virtual environment
@@ -29,12 +29,54 @@ source venv/bin/activate
2929
3030
# then run:
3131
python setup.py install
32+
33+
# alternatively, the depndencies can and might need to be installed using pip:
34+
pip install -r requirements.txt
3235
```
3336

37+
:warning: A internet connection is required for the installation as the setup script will download the required
38+
dependencies. Without an internet connection or cached versions of the required dependencies, the installation will fail
39+
with an error code 1!
40+
3441
This will install all required dependencies including the NOREC4DNA framework in the virtual environment.
3542
The installation should take less than 5 minutes on a typical desktop pc, but can take longer if an older pip version is
3643
used or if dependency conflicts exists (e.g. if no virtual environment is used).
3744

45+
# Concept:
46+
47+
As already mentioned, this tool aims to provide a way to recover data encoded using fountain codes.
48+
Compared to conventional error correction, our approach aims to recover data without additional overhead through the
49+
dependencies between the encoded chunks or - if an automatic recovery is not possible - by using information about the
50+
encoded data. This information can be used to manually tag chunks as corrupt or correct or to use plugins to identify
51+
corrupt data and correct it.
52+
Additionally, it is possible to interface with external file recovery tools which can be used to partially repair a file
53+
and then load this file into DR4DNA to automatically repair the rest of the file.
54+
55+
![DR4DNA-impl.svg](DR4DNA-impl.svg)
56+
This tool is uses a plugin system to allow the user to define custom repair methods while integrating the bare logic in
57+
a backend. Our backend uses the Plotly / DASH Framework to serve the content as a lightweight Web-App. While this
58+
event-driven design allows for a flexible and extendable architecture, it may reduce readability of the code.
59+
60+
## Automatic recovery:
61+
62+
The generated and stored packets of a fountain code can be represented as a linear equation system, where solving it (
63+
e.g. using Gaussian elimination or belief propagation) yields the orignial message.
64+
By calculating A^-1 while solving, it is possible to calculate which packets were used for each chunk during the
65+
decoding.
66+
67+
If the linear equation system is inconsistent (multiple differing results can be derived from the same equation system),
68+
the corrupt packet can be identified by permutating the equation system and comparing the used packets for chunk whith
69+
equal and differing content. Using the difference (error delta) of the differing chunks, the corrupt packet can
70+
additionally be corrected.
71+
72+
## Manual or content based recovery:
73+
If the equation system is consistent, the corrupt packet has to be found either using:
74+
75+
- manual tagging of chunks as corrupt or correct until only one possible corrupt packet is left (using A^-1)
76+
- using plugins to identify corrupt chunks and, if possible, correct them.
77+
- using external tools in combination with the UploadRepair plugin to first partially repair a file and then use DR4DNA
78+
to automatically repair any remaining errors.
79+
3880
# Usage
3981

4082
```
@@ -86,16 +128,17 @@ While using external tools to correct the image can be easier, that the modified
86128
same configuration (width, height, color depth, compression, etc.) as the original image!
87129
A partially repaired version of the image can be found in `eval/cornell_partial_repaired.bmp`.
88130
To repair the image, the user has to:
131+
89132
1) Press `Reload image` to initialize the canvas (optional for external image repair)
90133
2) Press `Download data` to download the image
91134
3) Correct a view pixel in the image
92-
4) Drag and Drop the partially repaired image into the plugin
93-
5) Find incorrect positions and (in)correct columns (optional as loading the image will automatically tag the rows)
94-
6) Press `Automatic Repair`
95-
7) `Reload image` again to see the repaired image
135+
4) Drag and Drop the partially repaired image into the plugin
136+
5) Find incorrect positions and (in)correct columns (optional as loading the image will automatically tag the rows)
137+
6) Press `Automatic Repair`
138+
7) `Reload image` again to see the repaired image
96139
8) `Save file` to save the repaired image.
97140

98-
This process is analog to the `Upload repair` plugin, which can be used to upload any partially repaired file.
141+
This process is analog to the `Upload repair` plugin, which can be used to upload any partially repaired file.
99142

100143
3rd example:
101144

0 commit comments

Comments
 (0)