\subsection{Mapfile structure}\label{subsec:mapfile-structure}

Mapfiles created by \texttt{ddrescue} use a compact text format to store meta information
about the data rescuing process and the information about the rescuing status of blocks\cite{ddrescue}.
A simple exemplary mapfile is shown below.

\begin{tcbcode}{Example mapfile}
# Mapfile. Created by GNU ddrescue version 1.27
# Command line: ddrescue /dev/sdb sdb.img sdb.map
# Start time:   2024-02-08 06:56:57
# Current time: 2024-02-08 06:56:59
# Copying non-tried blocks... Pass 1 (forwards)
# current_pos  current_status  current_pass
0x00970000     ?               1
#      pos        size  status
0x00000000  0x02200000  +
0x02200000  0x00000001  -
0x02200001  0x3F690000  ?
\end{tcbcode}

The mapfile consists of three main parts:

The \textbf{heading comments} comments provide metadata about the mapfile, as the version of ddrescue or ddrescuelog that created it,
the command-line parameters used during the operation and the start time of the program.
If it was created by ddrescue, it also includes the current save time and a copy of the status message from the screen (e.g., copying, trimming, finished).

The first non-comment line, the \textbf{status line}, contains the position being tried in the input file,
a status character indicating the type of operation (e.g., copying, trimming, scraping)
and a positive integer denoting the current pass in the current phase.
The status line helps efficient resumption of copying or retrying phases.

The other non-comment lines each describe a \textbf{data block}, containing the starting position of the block in the input file,
the size of the block in bytes and a status character indicating the block’s state (e.g., copied, trimmed, scraped).

\subsection{Parsing in Python}\label{subsec:parsing-in-python}
The Python function \texttt{parse\_mapfile} implemented in \texttt{ddrescue\_tui\_parser.py} is designed to parse such mapfiles.
It takes as input the path to the mapfile and the desired resolution for the output array.
The function performs several steps of validation and parsing, using the module \texttt{numpy}\cite{numpy}:

\begin{itemize}
\item It checks the validity of the input parameters.
If the file path is not valid or the resolution parameters are not integers greater than 1, it returns with an error message.
\item It opens the mapfile and reads it line by line, distinguishing between comment lines and data lines.
The first line is used to check whether the opened file is actually a mapfile, otherwise the function returns an error message.
\item It parses the comment lines to extract general information about the process, such as the version of ddrescue that created the mapfile,
the command-line parameters used and the direction of the reading process (forwards or backwards).
\item It parses the data lines to create custom \texttt{MapEntry} objects, each representing a block of data.
The \texttt{MapEntry} object has a position, size, and status, which are extracted from the data line.
The status converted to a numerical value, which can later be used for plotting the information.
\item After parsing all lines of the mapfile, the function sorts the list of \texttt{MapEntry} objects by position
to retrieve information about the total size from the last block of data.
It then transforms this list into a 1D numpy array with the length of the desired plot resolution,
with each element representing the status of multiple disk blocks.
As the resolution of the plot is usually several orders of magnitude smaller than the number of blocks on the disk,
some information is lost when the status is compressed in this way.
The highest numerical status value determines which status a compressed block receives;
the values were assigned in such a way that the most interesting information is retained in the author's opinion.
\item Finally, the function reshapes the 1D numpy array into a 2D numpy array based on the provided resolution.
It also updates the current position in the array based on the current position given in the mapfile.
\end{itemize}

The function returns the 2D numpy array and a dictionary containing the general information.
This information will be used to visualize the status of different blocks of data in a disk imaging process
and provide context about the process, as described in the following sections.