To evaluate our autoscaling system described above, we ran experiments
on two infrastructures: a homogeneous one (the DAS-4, a multi-cluster system
hosted by universities in The Netherlands~\cite{das4}) and a heterogeneous
one (the Amazon EC2 cloud~\cite{amazonEC2}). The goal of our experiments
was to evaluate and compare the three classes of customers by how well they fulfill
the SLOs and by the amount of resources they allocate.

%In this section we conducted our experiments on a heterogeneous infrastructure like Amazon EC2~\cite{amazonEC2}, and on a homogeneous infrastructure like DAS-4 (the Distributed ASCI Supercomputer 4)~\cite{das4}. In our experiment campaign, we compared the degree of SLO enforcement and resource consumption for each provisioning algorithm implemented in ConPaaS.

%DAS-4 is the Dutch Computational Infrastructure, a six-cluster wide-area distributed system designed with research purposes

\textbf{Testbed configuration:}  As a representative scenario, we deployed the MediaWiki application using ConPaaS on both infrastructures, and we ran the Wikibench tools with a 10\% sample of a real Wikipedia access trace for 24hours.
%Consequently, our goal is to evaluate the behavior of the provisioning algorithms, when scaling out and back the number of VMs hosting PhP servers to guarantee several performance requirements, referred to as SLO.  Accordingly, some assumptions were made:
We configured the experiments as follows:

\begin{itemize}
\item  Response times from static requests were not analyzed due to its lightweight nature.

\item The monitoring data was collected over a reporting period of 5 minutes.

\item We fixed a SLO of 700 milliseconds at the service's side.

\item We fixed a SLO penalty to 0.03\$ per violation.

\item The algorithms used the same statistically-chosen performance threshold ranges.

\item A minimum interval of 10 minutes has been established between scaling actions to avoid excessive oscillations.
\end{itemize}

%To provide the Wikipedia services, an initial configuration was composed of 4 VMs, and 1 VM to host the Wikibench tools. The 4 VMs include a PhP service manager VM, a PhP agent VM, a web server and a http-proxy agent VM (both in the same VM), and finally a MySQL agent VM to store the English Wikipedia data, as explained in Section~\ref{wikipedia}.

\subsection{Heterogeneous Infrastructure}

\begin{table}
  {\scriptsize
\begin{center}
    \begin{tabular}{  | c | c | c | c | c |}
    \hline
      \textbf{Name}  & \textbf{Configuration} & \textbf{Cost/hr} \\ \hline
   \textit{m1.small}   & 1-ECU~\footnote{One EC2 compute unit provides the equivalent CPU capacity of a 1.0-1.2 GHz 2007 Opteron or 2007 Xeon processor.}  -- 1.5Gb RAM&  0.06\$ \\ \hline
   \textit{m1.medium}   & 2-ECU -- 4Gb RAM&  0.12\$ \\ \hline
\textit{c1.medium} & 5-ECU -- 3Gb RAM& 0.145\$   \\ \hline
\textit{m1.large} & 4-ECU -- 8Gb RAM& 0.24\$   \\ \hline
 \end{tabular}
\end{center}
\vspace{-5mm}
\caption{EC2 instance type characteristics.}
\label{EC2instances}
}
\end{table}

\subsubsection{SLA fulfillment: low}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/ec2/proxyDataPoints_output.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Response time values for a bronze customer.}
  \label{lowResponseTime}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/ec2/proxyDataPoints_output_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Zoom outage for a bronze customer.}
  \label{zoomOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/ec2/inst_type_machines.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Cloud instances provisioned for a bronze customer.}
  \label{lowInstances}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/ec2/inst_type_machines_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Resource utilization during the outage for a bronze customer.}
  \label{resOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/ec2/penaltyVScost.eps}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Infrastructure cost vs SLO violation penalty for a bronze customer.}
  \label{lowPenalty}
\end{figure}

\subsubsection{SLA fulfillment: medium}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/ec2/proxyDataPoints_output.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Response time values for a silver customer.}
  \label{mediumResponseTime}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/ec2/proxyDataPoints_output_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Zoom outage for a silver customer.}
  \label{zoomOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/ec2/inst_type_machines.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Cloud instances provisioned for a silver customer.}
  \label{mediumInstances}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/ec2/inst_type_machines_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Resource utilization during the outage for a silver customer.}
  \label{resOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/ec2/penaltyVScost.eps}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Infrastructure cost vs SLO violation penalty for a silver customer.}
  \label{mediumPenalty}
\end{figure}

\subsubsection{SLA fulfillment: high}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/ec2/proxyDataPoints_output.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Response time values for a gold customer.}
  \label{highResponseTime}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/ec2/proxyDataPoints_output_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Zoom outage for a gold customer.}
  \label{zoomOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/ec2/inst_type_machines.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Cloud instances provisioned for a gold customer.}
  \label{highInstances}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/ec2/inst_type_machines_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Resource utilization during the outage for a gold customer.}
  \label{resOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/ec2/penaltyVScost.eps}
  \end{center}
\vspace{-5mm}
  \caption{EC2: Infrastructure cost vs SLO violation penalty for a gold customer.}
  \label{highPenalty}
\end{figure}

\begin{table*}\label{summaryEC2}
  {\scriptsize
\begin{center}
    \begin{tabular}{  | c | c | c | c | c |}
    \hline
         \textbf{Name}  & \textbf{SLO Violations} & \textbf{Decisions}  & \textbf{Cost}  & \textbf{Cost violations} \\ \hline
   \textit{Bronze}   &  1299 &  23 &  38.275\$ \$ & 38.97 \$ \\ \hline
   \textit{Silver}  &  461 &  27 &  47,555\$ \$ &  13.83 \$ \\ \hline
\textit{Gold} &   1007  &  19 &  59.4\$ \$ & 25.77 \$ \\ \hline

 \end{tabular}
\end{center}
\vspace{-5mm}
\caption{Analysis of results on EC2}
\label{summaryEC2}
}
\end{table*}

%%% EXPERIMENTS DAS4 %%%%

\subsection{Homogeneous Infrastructure}

\begin{table}\label{DAS4instances}
  {\scriptsize
\begin{center}
    \begin{tabular}{  | c | c | c | c | }
    \hline
       \textbf{Name}  & \textbf{Configuration} & \textbf{Cost/hr} \\ \hline
   \textit{small}   & 1-core 2.4Ghz -- 1Gb RAM&  0.115\$ \\ \hline
   \textit{medium}   & 4-core 2.4Ghz  -- 4Gb RAM&  0.23\$ \\ \hline
\textit{highcpu-medium} & 6-core 2.4Ghz -- 3Gb RAM& 0.28\$   \\ \hline
\textit{large} & 8-core 2.4Ghz  -- 8Gb RAM& 0.46\$   \\ \hline

 \end{tabular}
\end{center}
\vspace{-5mm}
\caption{DAS4 instance type characteristics.}
\label{DAS4instances}
}
\end{table}

\subsubsection{SLA fulfillment: low}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/das/proxyDataPoints_output.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Response time values for a bronze customer.}
  \label{lowResponseTime}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/das/proxyDataPoints_output_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Zoom outage for a bronze customer.}
  \label{zoomOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/das/inst_type_machines}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Cloud instances provisioned for a bronze customer.}
  \label{lowInstances}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/das/inst_type_machines_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Resource utilization during the outage for a bronze customer.}
  \label{resOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/low/das/penaltyVScost.eps}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Infrastructure cost vs SLO violation penalty for a bronze customer.}
  \label{lowPenalty}
\end{figure}

\subsubsection{SLA fulfillment: medium}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/das/proxyDataPoints_output.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Response time values for a silver customer.}
  \label{mediumResponseTime}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/das/proxyDataPoints_output_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Zoom outage for a silver customer.}
  \label{zoomOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/das/inst_type_machines.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Cloud instances provisioned for a silver customer.}
  \label{mediumInstances}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/das/inst_type_machines_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Resource utilization during the outage for a silver customer.}
  \label{resOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/medium/das/penaltyVScost.eps}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Infrastructure cost vs SLO violation penalty for a silver customer.}
  \label{mediumPenalty}
\end{figure}

\subsubsection{SLA fulfillment: high}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/das/proxyDataPoints_output.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Response time values for a gold customer.}
  \label{highResponseTime}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/das/proxyDataPoints_output_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Zoom outage for a gold customer.}
  \label{zoomOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/das/inst_type_machines.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Cloud instances provisioned for a gold customer.}
  \label{highInstances}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/das/inst_type_machines_filtered.pdf}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Resource utilization during the outage for a gold customer.}
  \label{resOutage}
\end{figure}

\begin{figure}
  \begin{center}
    \includegraphics[width=.85\linewidth]{images/exps2011/high/das/penaltyVScost.eps}
  \end{center}
\vspace{-5mm}
  \caption{DAS4: Infrastructure cost vs SLO violation penalty for a gold customer.}
  \label{highPenalty}
\end{figure}

\begin{table*}
  {\scriptsize
\begin{center}
    \begin{tabular}{  | c | c | c | c | c |}
    \hline
         \textbf{Name}  & \textbf{SLO Violations} & \textbf{Decisions}  & \textbf{Cost}  & \textbf{Cost violations} \\ \hline
   \textit{Bronze}   &  438 &  22 &  49.98\$ \$ & 13.14 \$ \\ \hline
   \textit{Silver}  &  150 &  9 &  42.665\$ \$ &  4.5 \$ \\ \hline
\textit{Gold} &  142 & 27 & 51.377\$ \$ & 3.81 \$ \\ \hline

 \end{tabular}
\end{center}
\vspace{-5mm}
\caption{Analysis of results on DAS4}
\label{summaryDAS4}
}
\end{table*}


\section{Future Work}
\label{sec:future-work}

In this project, we've investigated the possibility of utilizing ultrasound to achieve semantic localization. The characteristics of ultrasound is nice to cover each room and not crossing any walls. This is perfect for room-level detection and potentially for cubicle-level (since there is still such blocking board between cubicles). But for open area such as the Exploratorium at San Francisco, this won't work such well. But the inaudibility of ultrasound and the slow speed (in comparison to light and electromagnetic wave) will enable time-of-flight (TOF) based localization. Further investigation can be done for this extension.

On the other hand, we haven't utilized other sensors on the mobile phone to perform dead reckoning (DR). Many recent researches have been showing that using particle filters for the accelerometer readings can determine the trajectory of users. But such approach is undermined by the drift caused by the error of sensor measurement. The ultrasound localization could act as landmarks to correct such drift, and many works might be done in this direction.
%% Master
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ee149"
%%% End:


\subsection{Inception modules}


\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage{algorithmic}
\usepackage{algorithm}
\usepackage{amsmath}
\usepackage{xspace}
\usepackage{program}

\begin{document}

\section{Game Tree operations}

\begin{algorithm}
\begin{program}
    |movePairs|(gt) \rcomment{Returns a list of move pairs}

    |children|(gt) \rcomment{Returns successor game trees}

    |copy|(gt) \rcomment{Returns the copy id for this node of the tree}

    |copyHat|(gt) \rcomment{Returns the copy id for hat moves in this node of the tree}

    |rank|(gt) \rcomment{Returns the rank for this node of the tree}

    |copies|(gt) \rcomment{Returns all copy ids in the tree}

\end{program}
\end{algorithm}

\section{Universal/Environment Player}
$$
F_E(s, gt) = s \land B_E(rank(gt), copies(gt)) \land M_E(gt) \land E(gt)
$$

$$
B_E(R, C) = \bigwedge\limits_{w \in winningEx} \bigwedge\limits_{c = 0}^C \bigwedge\limits_{k = 0}^R \lnot(w_k^c)
$$

$$
M_E(gt) = \bigwedge\limits_{(m1, m2, c) \in movePairs(gt)} (m1_{rank(gt)}^{copy(gt)} \land (m2_{rank(gt)}^{copyHat(gt)} \land (Vu_{rank(gt)}^{copyHat(gt)} \Rightarrow m2_{rank(gt)}^{copy(gt)})) \land M_E(c))
$$

\[
E(gt) =
\begin{cases}
    \bigwedge\limits_{r = 1}^{rank(gt)} T(x_r^{copy(gt)}, x_{r-1}^{copy(gt)}) \land G(x_{r-1}^{copy(gt)}) & \text{gt is leaf} \\
    \\
    T(x_{rank(gt)}^{copy(gt)}, x_{rank(gt)-1}^{copy(gt)}) \land G_{rank(gt)-1}^{copy(gt)} \land \lbrace\bigwedge\limits_{c \in children(gt)} E(c)\rbrace & \text{otherwise}
\end{cases}
\]

\section{Existential/Driver Player}

$$
F_D(s, gt) = s \land B_D(rank(gt), copies(gt)) \land M_D(gt) \land D(gt)
$$

$$
B_D(R, C) = \bigwedge\limits_{k = 0}^R \bigwedge\limits_{w \in winningUn(k)} \bigwedge\limits_{c = 0}^C \bigwedge\limits_{r = 0}^k \lnot(w_r^c)
$$

$$
M_D(gt) = \bigwedge\limits_{(m1, m1, c) \in movePairs(gt)} (m1_{rank(gt)}^{copyHat(gt)} \land (Ve_{rank(gt)}^{copyHat(gt)} \Rightarrow m1_{rank(gt)}^{copy(gt)})) \land (m2_{rank(gt)}^{copy(gt)} \land M_D(c))
$$

\[
D_{tree}(gt) =
\begin{cases}
    D_{rank}(rank(gt), copy(gt)) & \text{gt is leaf} \\
    \\
    T(x_{rank(gt)}^{copy(gt)}, x_{rank(gt)-1}^{copy(gt)}) \land (G_{rank(gt)-1}^{copy(gt)} \lor \bigwedge\limits_{c \in children(gt)} D(c)) & \text{otherwise}
\end{cases}
\]

\[
    D_{rank}(r, c) = T(x_r^{c}, x_{r-1}^{c}) \land (G(x_{r-1}^{c}) \lor D(r-1, c))
\]
\[
    D_{rank}(0, c) = False
\]

\end{document}


\subsection{Cryptographic Functions}
\subsubsection{sec\_encrypt}
\nm{3X}{sec\_encrypt}{Encrypt octetstring}
\label{sec_encrypt}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_encrypt} {\em (in\_octets, out\_bits, more, key)} \\
OctetString *{\em in\_octets}; \\
BitString *{\em out\_bits}; \\
More {\em more}; \\
Key *{\em key};
\hl{Parameter}
\parname  {{\em in\_octets}}
\pardescript  {OctetString of the data to be encrypted.}

\parname  {{\em out\_bits}}
\pardescript  {BitString of the encrypted data. Memory must be provided by the calling program.}

\parname  {{\em more}}
\pardescript  {MORE: More data will follow for this encryption process. \\
                  END: Last data of this encryption process.}

\parname  {{\em key}}
\pardescript  {Structure which identifies the encryption key.}

\parname  {{\em Return Value}}
\pardescript  {Number of encrypted bits in {\em out\_bits}, or -1.}
\hl{Description}
Sec\_encrypt encrypts the input data of octetstring {\em in\_octets} and returns the encrypted data
in {\em out\_bits}. Several successive calls of sec\_encrypt can be chained
to one encryption process by means of {\em more}.

The number of octets in {\em in\_octets} is arbitrary. The number of bits in {\em out\_bits}
corresponds in case of {\em more} $=$ MORE to the parameters of the indicated algorithm
(e.g. a multiple of 64 in case of DES or DES3 algorithms and a multiple of keysize
in case of RSA). The remaining bits are collected by sec\_encrypt.

Sec\_encrypt puts the encrypted data into {\em out\_bits}\pf bits at the offset
{\em out\_bits}\pf nbits and returns the number of encrypted bits. In addition, this number is added
to {\em out\_bits}\pf nbits.
The calling program must provide {\em out\_bits}\pf nbits and {\em out\_bits}\pf bits and sufficient
memory in {\em out\_bits}\pf bits.
The amount of memory should be not less than
{\em in\_octets}\pf noctets $+$ ({\em out\_bits}\pf nbits) $/$ 8 $+$ $n$ with $n = 8$
in case of DES or DES3 algorithms and $n = keysize / 8$ in case of RSA.

Encryption key and corresponding algorithm are determined by parameter {\em key} as follows:
\be
\m If {\em key}\pf key is not the NULL pointer, the structure it points to
   contains algorithm identifier and key.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $>$ 0,
   key and algorithm identifier which are referenced by this number are used. This is a key
   previously installed under this reference with {\em sec\_gen\_key} or
   {\em sec\_put\_EncryptedKey}.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $=$ 0,
   {\em key}\pf pse\_sel indicates the PSE object which contains key and algorithm.
\ee

{\bf In case of RSA algorithm:}
\be
\m The encryption key which is of type BitString is supposed to be
   a {\bf public key}. It consists of the substructure described in
   SEC-PSE-OBJECTS(4), which in case of a public key consists of the
   modulus and the public exponent. Sec\_encrypt uses internally the
   decoding function {\em d\_KeyBits} to get the modulus {\em n} and the exponent {\em e}.
\m The octetstring passed through {\em in\_octets} is internally blocked into portions of
   {\em blocksize} bits, each block considered to represent a positive integer number with the first bit
   being the most significant bit. These blocks are encrypted into blocks of {\em keysize} bits
   (padded with trailing ZEROES) which in turn are combined into the bitstring {\em out\_bits}, i.e
   the bitstring of the encrypted data consists of more bits than the octetstring of the cleartext data
   according to the relation between {\em blocksize} and {\em keysize}.
   The length of the encrypted data is always a multiple of {\em keysize} bits.
   {\em blocksize} is derived from {\em keysize} as the largest multiple of octets which consists of
   less bits than {\em keysize} (for instance $keysize = 512$ leads to $blocksize = 63$).
\m There is no special mechanism to encode the length of the original plaintext prior
   to encryption. Decrypting encrypted (with {\em sec\_encrypt}) data with {\em sec\_decrypt}
   leads to a result with a length of a multiple of {\em blocksize} octets, i.e. the decrypted
   plaintext is longer than the original plaintext with trailing zeroes.
\ee
{\bf In case of DES or DES3 algorithm:}
   The length of the encryption result is always a multiple of 64 bits.

\subsubsection{sec\_decrypt}
\nm{3X}{sec\_decrypt}{Decrypt bitstring}
\label{sec_decrypt}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_decrypt} {\em (in\_bits, out\_octets, more, key)} \\
BitString *{\em in\_bits}; \\
OctetString *{\em out\_octets}; \\
More {\em more}; \\
Key *{\em key};
\hl{Parameter}
\parname  {{\em in\_bits}}
\pardescript  {BitString of the data to be decrypted.}

\parname  {{\em out\_octets}}
\pardescript  {OctetString of the decrypted data. Memory must be provided by the calling program.}

\parname  {{\em more}}
\pardescript  {MORE: More data will follow for this decryption process. \\
                  END: Last data of this decryption process.}

\parname  {{\em key}}
\pardescript  {Structure which identifies the decryption key.}

\parname  {{\em Return Value}}
\pardescript  {Number of decrypted octets in {\em out\_octets}, or -1.}
\hl{Description}
Sec\_decrypt decrypts the input data of bitstring {\em in\_bits} and returns the decrypted data
in {\em out\_octets}. Several successive calls of sec\_decrypt can be chained
to one decryption process by means of {\em more}.

The number of bits in {\em in\_bits} is arbitrary (see remark below for DES). The number of octets in {\em out\_octets}
corresponds in case of {\em more} $=$ MORE to the parameters of the indicated algorithm
(e.g. a multiple of eight in case of DES or DES3 algorithms and a multiple of blocksize/8
in case of RSA). The remaining octets are collected by sec\_decrypt.

Sec\_decrypt puts the decrypted data into {\em out\_octets}\pf octets at the offset
{\em out\_octets}\pf noctets and returns the number of decrypted octets. In addition, this number is added
to {\em out\_octets}\pf noctets.
The calling program must provide {\em out\_octets}\pf noctets and {\em out\_octets}\pf octets and sufficient
memory in {\em out\_octets}\pf octets.
The amount of memory should be not less than
({\em in\_bits}\pf nbits) $/$ 8 $+$ {\em out\_octets}\pf noctets $+$ $n$ with $n = 8$
in case of DES or DES3 algorithms and $n = keysize / 8$ in case of RSA.

Decryption key and corresponding algorithm are determined by parameter {\em key} as follows:
\be
\m If {\em key}\pf key is not the NULL pointer, the structure it points to
   contains algorithm identifier and key.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $>$ 0,
   key and algorithm identifier which are referenced by this number are used. This is a key
   previously installed under this reference with {\em sec\_gen\_key} or
   {\em sec\_put\_EncryptedKey}.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $=$ 0,
   {\em key}\pf pse\_sel indicates the PSE object which contains key and algorithm.
\ee

{\bf In case of RSA algorithm:}
\be
\m The decryption key which is of type BitString is supposed to be
   a {\bf secret key}. It consists of the substructure described in
   SEC-PSE-OBJECTS(4), which in case of a secret key consists of the secret
   prime factors. Sec\_decrypt uses internally the
   decoding function {\em d\_KeyBits} to get the prime factors {\em p} and {\em q}.
\m The bitstring passed through {\em in\_bits} is internally blocked into portions of
   {\em keysize} bits, each block considered to represent a positive integer number with the first bit
   being the most significant bit. These blocks are decrypted into blocks of {\em blocksize} bits
   (padded with trailing ZEROES) which in turn are combined into the octetstring {\em out\_octets}, i.e
   the octetstring of the decrypted data consists of less bits than the bitstring
   of the encrypted data
   according to the relation between {\em blocksize} and {\em keysize}.
   The length of the decrypted data is always a multiple of {\em blocksize} octets.
   {\em blocksize} is derived from {\em keysize} as the largest multiple of octets which consists of
   less bits than {\em keysize} (for instance $keysize = 512$ leads to $blocksize = 63$).
\m Sec\_decrypt does not assume any specific padding prior encrypting in order to be able to
   restore the original plaintext length. This must be done by the application before
   calling  sec\_encrypt and after calling sec\_decrypt.
\m Since there is no special mechanism to encode the length of the original plaintext prior
   to encryption, decrypting encrypted (with {\em sec\_encrypt}) data with {\em sec\_decrypt}
   leads to a result which is longer than the original plaintext with trailing zeroes.
\ee
{\bf In case of DES or DES3 algorithm:} \\ [1em]
   While the number of bits in {\em in\_bits} is arbitrary for each single call to
   {\em sec\_decrypt}, the number of bits of the input data for the whole
   decryption process (until {\em more} $=$ END) must be a multiple of 64.

\subsubsection{sec\_hash}
\nm{3X}{sec\_hash}{Hash octetstring}
\label{sec_hash}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_hash} {\em (in\_octets, hash\_result, more, alg\_id, hash\_input)} \\
OctetString *{\em in\_octets}; \\
OctetString *{\em hash\_result}; \\
More {\em more}; \\
AlgId *{\em alg\_id}; \\
HashInput *{\em hash\_input};
\hl{Parameter}
\parname  {{\em in\_octets}}
\pardescript  {OctetString of the data to be hashed.}

\parname  {{\em hash\_result}}
\pardescript  {OctetString of the hash result. Memory is provided by the called program.}

\parname  {{\em more}}
\pardescript  {MORE: More data will follow for this hash process. \\
                  END: Last data of this hash process.}

\parname  {{\em alg\_id}}
\pardescript  {Algorithm identifier of the hash function to be used. Each algorithm which is of type
              HASH or SIG (see INTRO(3)) is possible, e.g.: \\
                  sqmodn \\
                  md2 \\
                  md4 \\
                  md5 \\
                  sha \\
                  sqmodnWithRsa \\
                  md2WithRsa \\
                  md4WithRsa \\
                  md5WithRsa \\
                  md2WithRsaEncryption \\
                  md4WithRsaEncryption \\
                  md5WithRsaEncryption \\
                  rsa\_md2\_pem \\
                  rsa\_md5\_pem} \\ [0.5cm]
\parname  {{\em hash\_input}}
\pardescript  {Additional algorithm specific parameters.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
OctetString {\em in\_octets} is hashed into octetstring {\em hash\_result} using the algorithm
{\em alg\_id}. {\em More} allows to chain several successive calls of sec\_hash to one
hash process.

The number of octets in {\em in\_octets} is arbitrary. Sec\_hash puts the hash value as octetstring into
{\em hash\_result} in case of {\em more} $=$ END. The called program provides sufficient memory
in {\em hash\_result}.

In case of sqmodn or sqmodnWithRsa, {\em hash\_input} is a BitString which contains the
public key (as ASN.1 encoded sequence of the modulus $n$ and the public
exponent $e$). Sec\_hash extracts the modulus $n$ from this BitString by using the function
d\_KeyBits.

\subsubsection{sec\_sign}
\nm{3X}{sec\_sign}{Sign octetstring}
\label{sec_sign}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_sign} {\em (in\_octets, signature, more, key, hash\_input)} \\
OctetString *{\em in\_octets}; \\
Signature *{\em signature}; \\
More {\em more}; \\
Key *{\em key}; \\
HashInput *{\em hash\_input};
\hl{Parameter}
\parname  {{\em in\_octets}}
\pardescript  {OctetString of the data to be signed.}

\parname  {{\em signature}}
\pardescript  {Returned signature. Memory is provided by the called program.}

\parname  {{\em more}}
\pardescript  {MORE: More data will follow for this sign process. \\
                  END: Last data of this sign process.}

\parname  {{\em key}}
\pardescript  {Structure which identifies the signature key.}

\parname  {{\em hash\_input}}
\pardescript  {Additional algorithm specific parameters.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
In case of {\em more} $=$ MORE or END sec\_sign hashes {\em in\_octets} onto
an internal hash value, using the algorithm as described below.
If {\em hash\_input} is not the NULL pointer, this parameter is taken
as initial value for the hash function.
In case of {\em more} $=$ END this hash value is encrypted using key and
algorithm as described below and returned as BitString in {\em signature}\pf signature.
All necessary memory for returned information will be provided by the
called program.

The signature key is determined by parameter {\em key} as follows:
\be
\m If {\em key}\pf key is not the NULL pointer, the structure it points to
   contains the key.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $>$ 0,
   the key which is referenced by this number is used. This is a key
   previously installed under this reference with {\em sec\_gen\_key} or
   {\em sec\_put\_EncryptedKey}.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $=$ 0,
   {\em key}\pf pse\_sel indicates the PSE object which contains the key.
\ee
The algorithm to be used is determined in the following order:
\be
\m If {\em key}\pf alg is not the NULL pointer, this algorithm
   is used.
\m If {\em signature}\pf signAI is not the NULL pointer, this algorithm
   is used.
\m Otherwise, the algorithm associated to the key is used.
\ee
   The used algorithm identifier
   is returned in {\em signature}\pf signAI.
   All necessary memory allocation is done by the called program.

If the algorithm is sqmodnWithRsa, {\em hash\_input} is a BitString which contains the
public key (as ASN.1 encoded sequence of the modulus $n$ and the public
exponent $e$). The modulus $n$ is extracted from this BitString by using the function
d\_KeyBits.

\subsubsection{sec\_verify}
\nm{3X}{sec\_verify}{Verify signature}
\label{sec_verify}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_verify} {\em (in\_octets, signature, more, key, hash\_input)} \\
OctetString *{\em in\_octets}; \\
Signature *{\em signature}; \\
More {\em more}; \\
Key *{\em key}; \\
HashInput *{\em hash\_input};
\hl{Parameter}
\parname  {{\em in\_octets}}
\pardescript  {OctetString of the input data for the verification.}

\parname  {{\em signature}}
\pardescript  {Signature to be verified.}

\parname  {{\em more}}
\pardescript  {MORE: More input data will follow for this verification process. \\
                  END: Last input data of this verification process.}

\parname  {{\em key}}
\pardescript  {Structure which identifies the verification key.}

\parname  {{\em hash\_input}}
\pardescript  {Additional algorithm specific parameters.}

\parname  {{\em Return Value}}
\pardescript  {0 (verification positive) or -1.}
\hl{Description}
In case of {\em more} $=$ MORE or END sec\_verify hashes {\em in\_octets} onto
an internal hash value, using the algorithm as described below.
If {\em hash\_input} is not the NULL pointer, this parameter is taken
as initial value for the hash function.
In case of {\em more} $=$ END the signature given in {\em signature}\pf signature
is decrypted using key and algorithm as described below, and the result is compared
with the previously computed internal hash value. If both are equal, the verification
is positive.

The verification key is determined by parameter {\em key} as follows:
\be
\m If {\em key}\pf key is not the NULL pointer, the structure it points to
   contains the key.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $>$ 0,
   the key which is referenced by this number is used. This is a key
   previously installed under this reference with {\em sec\_gen\_key} or
   {\em sec\_put\_EncryptedKey}.
\m If {\em key}\pf key is the NULL pointer and {\em key}\pf keyref $=$ 0,
   {\em key}\pf pse\_sel indicates the PSE object which contains the key.
\ee
The algorithm to be used is determined as follows:
\be
\m If {\em signature}\pf signAI\pf objid is not the NULL pointer, the algorithm
   determined by this object identifier is used.
\m Otherwise, i.e. if either {\em signature}\pf signAI or {\em signature}\pf signAI\pf objid
   is the NULL pointer, the algorithm
   associated to the key determined by parameter {\em key} as above is used.
\ee
If the algorithm is sqmodnWithRsa, {\em hash\_input} is a BitString which contains the
public key (as ASN.1 encoded sequence of the modulus $n$ and the public
exponent $e$). The modulus $n$ is extracted from this BitString by using the function
d\_KeyBits.

\subsubsection{sec\_gen\_key}
\nm{3X}{sec\_gen\_key}{Generate DES or RSA key}
\label{sec_gen_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_gen\_key} {\em (key, replace)} \\
Key *{\em key}; \\
Boolean {\em replace};
\hl{Parameter}
\parname  {{\em key}}
\pardescript  {Structure which determines the generated key.}

\parname  {{\em replace}}
\pardescript  {if FALSE, do not overwrite existing key.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_gen\_key generates a
\bi
\m  DES key,
    if the algorithm encryption method
    of {\em key}\pf key\pf subjectAI (as returned by aux\_ObjId2AlgEnc()) is DES.

    A DES key is a 64 bit long BitString.
\m  DES3 key,
    if the algorithm encryption method
    of {\em key}\pf key\pf subjectAI (as returned by aux\_ObjId2AlgEnc()) is DES3.

    DES3 is triple block encryption in the fashion encryption(k1)-decryption(k2)-encryption(k1).
    A DES3 key is a 128 bit long BitString, the first 64 bits comprising k1 and the
    second 64 bits comprising k2.
\m  RSA key pair,
    if the algorithm encryption method
    of {\em key}\pf key\pf subjectAI (as returned by aux\_ObjId2AlgEnc()) is RSA.

    An RSA public key is a BitString
    which contains the ASN.1 DER code of
    \bvtab
    \4  SEQUENCE \{ \\
    \4  \2       n INTEGER,   \\
    \4  \2       e INTEGER  \\
    \4  \} \\
    \evtab
    $n$ is the modulus and $e$ is the public exponent.

    An RSA secret key is a BitString
    which contains the ASN.1 DER code of
    \bvtab
    \4  SEQUENCE \{ \\
    \4  \2       p INTEGER,   \\
    \4  \2       q INTEGER  \\
    \4  \} \\
    \evtab
    $p$ and $q$ are the two prime factors of the modulus.

\m  DSA key pair,
    if the algorithm encryption method
    of {\em key}\pf key\pf subjectAI (as returned by aux\_ObjId2AlgEnc()) is DSA.

    A DSA public key is a BitString
    which contains the ASN.1 DER code of
    \bvtab
    \4  SEQUENCE \{ \\
    \4  \2       key INTEGER, - - y (public key)   \\
    \4  \2       params DSAParameters OPTIONAL  \\
    \4  \} \\
    \evtab
    with
    \bvtab
    DSAParameters ::= SEQUENCE \{ \\
    \4  \2       prime1 [0] INTEGER, - - p \\
    \4  \2       prime2 [1] INTEGER, - - q \\
    \4  \2       base [2] INTEGER, - - g \\
    \4  \} \\
    \evtab

    A DSA secret key is a BitString
    which contains the ASN.1 DER code of
    \bvtab
    \4  SEQUENCE \{ \\
    \4  \2       key INTEGER, - - x (secret key)   \\
    \4  \2       params DSAParameters OPTIONAL  \\
    \4  \} \\
    \evtab
    with
    \bvtab
    DSAParameters ::= SEQUENCE \{ \\
    \4  \2       prime1 [0] INTEGER, - - p \\
    \4  \2       prime2 [1] INTEGER, - - q \\
    \4  \2       base [2] INTEGER, - - g \\
    \4  \} \\
    \evtab
\ei

The key is returned as follows in case of a DES key or DES3 key:
\be
\m If {\em key}\pf keyref $=$ 0 and {\em key}\pf pse\_sel is the NULL pointer, the generated key is
   returned as BitString in {\em key}\pf key\pf subjectkey. Memory is provided by the called program.
\m If {\em key}\pf keyref $=$ 0 and {\em key}\pf pse\_sel is not the NULL pointer, the generated key
   is stored in the PSE object specified by {\em key}\pf pse\_sel.
   The object will be created first. If the object exists already and {\em replace} is FALSE,
   {\em sec\_gen\_key} does not overwrite the object and returns -1.
\m If {\em key}\pf keyref $>$ 0, the generated key is stored under this key reference until it is
   deleted with sec\_del\_key.
   If the key reference exists already and {\em replace} is FALSE, {\em sec\_gen\_key}
   does not overwrite the key and returns -1.
\m If {\em key}\pf keyref $=$ -1, the generated key is stored under a key reference which is generated
   by sec\_gen\_key and returned in {\em key}\pf keyref. The key remains there until it is deleted
   with sec\_del\_key.
\ee
The keys are returned as follows in case of an RSA or DSA key pair:

The public key is returned in {\em key}\pf key\pf subjectkey. Memory is provided by the called program.
The private key is stored under a key reference or in a PSE object as described above for a DES key in
cases 2, 3, or 4.

\subsubsection{sec\_get\_key}
\nm{3X}{sec\_get\_key}{Get key from key pool or from PSE}
\label{sec_get_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_get\_key} {\em (keyinfo, keyref, key)} \\
KeyInfo *{\em keyinfo}; \\
KeyRef {\em keyref}; \\
Key *{\em key};
\hl{Parameter}
\parname  {{\em keyinfo}}
\pardescript  {KeyInfo structure which holds the returned key.}

\parname  {{\em keyref}}
\pardescript  {Reference to an existing key.}

\parname  {{\em key}}
\pardescript  {Structure which determines the key.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
If {\em keyref} is non zero, the content of the keyinfo structure referenced
by {\em keyref} is restored from the key pool and returned
in {\em keyinfo}. The necessary memory in {\em keyinfo} is provided
by the called program.

If {\em keyref} is zero, and {\em key} is not the NULL pointer, {\em key}
refers to the key to be returned.

\subsubsection{sec\_put\_key}
\nm{3X}{sec\_put\_key}{Put key to the key pool with reference number}
\label{sec_put_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_put\_key} {\em (keyinfo, keyref)} \\
KeyInfo *{\em keyinfo}; \\
KeyRef {\em keyref};
\hl{Parameter}
\parname  {{\em keyinfo}}
\pardescript  {KeyInfo structure with the key to be stored in the key pool.}

\parname  {{\em keyref}}
\pardescript  {Reference to a non existing key.}

\parname  {{\em Return Value}}
\pardescript  {keyref or -1.}
\hl{Description}
The content of the given {\em keyinfo} is stored in the key pool according to {\em keyref}:
\be
\m If {\em keyref} $>$ 0, {\em keyinfo} is stored under this key reference until it is
   deleted with sec\_del\_key. {\em keyref} must not exist.
\m If {\em key}\pf keyref $=$ -1, {\em keyinfo} is stored under a key reference which is generated
   by sec\_put\_key and returned in the return value. It remains there until it is deleted
   with sec\_del\_key.
\ee

\subsubsection{sec\_del\_key}
\nm{3X}{sec\_del\_key}{Delete key by reference from key pool}
\label{sec_del_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_del\_key} {\em (keyref)} \\
KeyRef {\em keyref};
\hl{Parameter}
\parname  {{\em keyref}}
\pardescript  {Reference to an existing key.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
The key referenced by {\em keyref} is deleted from the key pool.

\subsubsection{sec\_get\_EncryptedKey}
\nm{3X}{sec\_get\_EncryptedKey}{Encrypt key}
\label{sec_get_enc_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_get\_EncryptedKey} {\em (encrypted\_key, plain\_key, encryption\_key)} \\
EncryptedKey *{\em encrypted\_key}; \\
Key *{\em plain\_key}; \\
Key *{\em encryption\_key};
\hl{Parameter}
\parname  {{\em encrypted\_key}}
\pardescript  {Encrypted key.}

\parname  {{\em plain\_key}}
\pardescript  {Structure which identifies the key to be encrypted.}

\parname  {{\em encryption\_key}}
\pardescript  {Structure which identifies the encryption key.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
The key identified by {\em plain\_key} is encrypted with the key and algorithm identified by
{\em encryption\_key} and returned in
{\em encrypted\_key}. All memory in {\em encrypted\_key} which is referred to by pointers
is provided by the called program.

This function is intended to support the so called ``hybrid method'' where information which
has to be transmitted confidentially is encrypted with the DES algorithm while the corresponding DES key
is transmitted in RSA encrypted form. Sec\_get\_encrypted\_key is useful for the sender
of such a key.

\subsubsection{sec\_put\_EncryptedKey}
\nm{3X}{sec\_put\_EncryptedKey}{Decrypt key}
\label{sec_put_decr_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_put\_EncryptedKey} {\em (encrypted\_key, plain\_key, decryption\_key, replace)} \\
EncryptedKey *{\em encrypted\_key}; \\
Key *{\em plain\_key}; \\
Key *{\em decryption\_key}; \\
Boolean {\em replace};
\hl{Parameter}
\parname  {{\em encrypted\_key}}
\pardescript  {Encrypted key.}

\parname  {{\em plain\_key}}
\pardescript  {Structure which determines the decrypted key.}

\parname  {{\em decryption\_key}}
\pardescript  {Structure which identifies the decryption key.}

\parname  {{\em replace}}
\pardescript  {If TRUE, replace existing key}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
The encrypted key given in {\em encrypted\_key} is decrypted with the key and algorithm identified by
{\em decryption\_key}. The decrypted key is handled according to {\em plain\_key} as follows:

If {\em plain\_key}\pf keyref $=$ 0 and {\em plain\_key}\pf pse\_sel is the NULL pointer, the decrypted key is
returned as BitString in {\em plain\_key}\pf key\pf subjectkey. Memory is provided by the called program.

If {\em plain\_key}\pf keyref $=$ 0 and {\em plain\_key}\pf pse\_sel is not the NULL pointer, the decrypted key
is stored in the PSE object specified by {\em plain\_key}\pf pse\_sel. The object must already exist.

If {\em plain\_key}\pf keyref $>$ 0, the decrypted key is stored under this key reference until it is
deleted with sec\_del\_key.

If {\em plain\_key}\pf keyref $=$ -1, the decrypted key is stored under a key reference which is generated
by sec\_put\_EncryptedKey and returned in {\em plain\_key}\pf keyref. The key remains there until it is deleted
with sec\_del\_key.

If the decrypted key is to be stored in the key\_pool or as PSE object, and a key with that
reference or name exists already, it will be replaced only in case of {\em replace} set to TRUE.

This function is intended to support the so called ``hybrid method'' where information which
has to be transmitted confidentially is encrypted with the DES algorithm while the corresponding DES key
is transmitted in RSA encrypted form. Sec\_put\_decrypted\_key is useful for the receiver
of such a key.

\subsubsection{sec\_string\_to\_key}
\nm{3X}{sec\_string\_to\_key}{Generate DES key from string}
\label{sec_string_to_key}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_string\_to\_key} {\em (pin, des\_key)} \\
char *{\em pin}; \\
Key *{\em des\_key};
\hl{Parameter}
\parname  {{\em pin}}
\pardescript  {PIN (Personal Identification Number) or password.}

\parname  {{\em des\_key}}
\pardescript  {Structure which determines the resulting DES key.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_string\_to\_key is a one-way function which generates a DES key from a PIN or password.
The resulting DES key is returned as specified by {\em des\_key}:
\be
\m If {\em des\_key}\pf keyref $=$ 0 and {\em des\_key}\pf pse\_sel is the NULL pointer, the generated key is
   returned as BitString in {\em des\_key}\pf key\pf subjectkey. Memory is provided by the called program.
\m If {\em des\_key}\pf keyref $=$ 0 and {\em des\_key}\pf pse\_sel is not the NULL pointer, the generated key
   is stored in the PSE object specified by {\em des\_key}\pf pse\_sel. The object must already exist.
\m If {\em des\_key}\pf keyref $>$ 0, the generated key is stored under this key reference until it is
   deleted with sec\_del\_key.
\m If {\em des\_key}\pf keyref $=$ -1, the generated key is stored under a key reference which is generated
   by sec\_string\_to\_key and returned in {\em des\_key}\pf keyref. The key remains there until it is deleted
   with sec\_del\_key.
\ee
The assigned algorithm identifier is {\em desCBC} in either case.

\subsubsection{sec\_random}
\nm{3X}{sec\_random}{Generate random octetstring, bitstring, characterstring, integer, long}
\label{random}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
OctetString {\bf *sec\_random\_ostr} {\em (noctets)} \\
unsigned int {\em noctets};

BitString {\bf *sec\_random\_bstr} {\em (nbits)} \\
unsigned int {\em nbits};

char {\bf *sec\_random\_str} {\em (nchar, chars)} \\
unsigned int {\em nchar}; \\
char *{\em chars};

int {\bf sec\_random\_int} {\em (r1, r2)} \\
int {\em r1, r2};

long {\bf sec\_random\_long} {\em (r1, r2)} \\
long {\em r1, r2};
\hl{Description}
Sec\_random\_* return each a randomly generated OctetString, BitString, or NULL-terminated
character string of the required length, and integer or long integer in the range between
{\em r1} and {\em r2} respectively. Memory is provided by the called program
where appropriate.

In sec\_random\_str the set of characters the returned character string shall consist of can
be specified in {\em chars}. If {\em chars} is the NULL pointer, the returned character string
consists of the ASCII representation of characters as defined by the ASN.1 type
PrintableString.
They consist of the characters
\begin{center}
{\small
A to Z \\
a to z \\
0 to 9 \\
' ( ) + , - . / : = ?
}
\end {center}

\subsubsection{sec\_create}
\nm{3X}{sec\_create}{Create PSE or PSE object}
\label{sec_create}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_create} {\em (pse\_sel)} \\
PSESel *{\em pse\_sel};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_create creates an entire PSE or a PSE object.
The object belongs to the application identified by {\em pse\_sel}\pf app\_name.
In case of the SW-PSE, the application name is the name of the corresponding directory.

{\em pse\_sel}\pf object.name is the name of the object to be created. It can be omitted
(NULL pointer) in order to create a new application. In case of the SW-PSE,
this creates the entire PSE, i.e. it creates a new directory
with the name {\em pse\_sel}\pf app\_name in the HOME directory of
the user.

The PIN which allows the creation of a new object in the PSE ist either specified in
{\em pse\_sel}\pf pin, or sec\_create asks for it interactively.
The PIN to be installed for the object
is either specified in {\em pse\_sel}\pf object.pin, or sec\_create asks for it interactively.
If the user returns CR only in this case, no PIN protection for the created object
is installed. All interactively entered PIN's are returned by sec\_create in the appropriate
parameter fields.

\subsubsection{sec\_delete}
\nm{3X}{sec\_delete}{Delete PSE object}
\label{sec_delete}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_delete} {\em (pse\_sel)} \\
PSESel *{\em pse\_sel};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_delete deletes a PSE object.
The object belongs to the application identified by {\em pse\_sel}\pf app\_name.
In case of the SW-PSE, the application name is the name of the corresponding directory.

{\em pse\_sel}\pf object.name is the name of the object to be deleted. It can be omitted
(NULL pointer) in case of the SW-PSE in order to delete the entire PSE. \\[1ex]
The PSE-PIN is either specified in
{\em pse\_sel}\pf pin, or sec\_delete asks for it interactively.
The object specific PIN, if any, is either specified in {\em pse\_sel}\pf object.pin,
or sec\_delete asks for it interactively.

\subsubsection{sec\_rename}
\nm{3X}{sec\_rename}{Rename an object in the PSE}
\label{sec_rename}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_rename} {\em (pse\_sel, name)} \\
PSESel *{\em pse\_sel}; \\
char  *{\em name};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em name}}
\pardescript  {the new name of the PSE object.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
The object of the PSE identified by {\em pse\_sel} will be renamed
with the name given in the second parameter. The contents of the
object will not be changed, but the Toc entry of this object
will reflect that change. If the call succeeds the function
returns 0, otherwise in case of errors -1.

\subsubsection{sec\_open}
\nm{3X}{sec\_open}{Open PSE or PSE object}
\label{sec_open}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_open} {\em (pse\_sel)} \\
PSESel *{\em pse\_sel};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_open opens a PSE object. If the object is PIN protected, sec\_open performs
all necessary actions for the PIN check.
The object belongs to the application identified by {\em pse\_sel}\pf app\_name.
In case of the SW-PSE the application name is the name of the corresponding directory.

{\em pse\_sel}\pf object.name is the name of the object to be opened. If {\em pse\_sel}\pf object.name
is the NULL pointer, sec\_open refers to the entire PSE. \\
If the object is PIN protected, the PIN check is performed with {\em pse\_sel}\pf object.pin.
If {\em pse\_sel}\pf object.pin is the NULL pointer, sec\_open asks for the PIN
interactively and returns the plain PIN in {\em pse\_sel}\pf object.pin.

Sec\_open returns a reference number for the application in {\em pse\_sel}\pf app\_id which
can be used instead of the application name during successive sec\_close, sec\_read,
or sec\_write calls.

\subsubsection{sec\_close}
\nm{3X}{sec\_close}{Close PSE object}
\label{sec_close}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_close} {\em (pse\_sel)} \\
PSESel *{\em pse\_sel};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_close closes a PSE object. This is a dummy operation in case of the SW-PSE. \\ [0.5cm]
In case of a SC, a closed object cannot be accessed anymore prior to reopen
it with sec\_open.

{\em pse\_sel}\pf app\_id can be used to pass a reference to an application which was generated
by sec\_open, instead of an application name.

\subsubsection{sec\_read}
\nm{3X}{sec\_read}{Read PSE object into an octetstring}
\addtotoc{sec\_read\_PSE}
\label{sec_read}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_read} {\em (pse\_sel, content)} \\
PSESel *{\em pse\_sel}; \\
OctetString *{\em content};

RC {\bf sec\_read\_PSE} {\em (pse\_sel, type, value)} \\
PSESel *{\em pse\_sel}; \\
ObjId *type; \\
OctetString *{\em value};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em content}}
\pardescript  {Decrypted content of the object identified by {\em pse\_sel}\pf object.name.}

\parname  {{\em type}}
\pardescript  {Object identifier of the PSE object.}

\parname  {{\em value}}
\pardescript  {Decrypted content of the objectValue part of the object
               identified by {\em pse\_sel}\pf object.name.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
{\bf Sec\_read} reads the PSE object -- identified by {\em pse\_sel}\pf object.name
and previously opened by sec\_open -- into octetstring {\em content}.
In case of PIN protection the octetstring is
decrypted before using the PIN which is either passed to the program through {\em pse\_sel}
or which was interactively asked for. Sec\_read reads the entire object.

Sec\_read provides {\em content}\pf noctets and allocates the necessary memory
in {\em content}\pf octets which can be released by the calling program using free().

In case of a SW-PSE, the object can be read without being opened before. It is recommended, however,
to use sec\_open before reading an object to be compatible with applications using
a SC environment. \\ [1em]
{\bf Sec\_read\_PSE} returns the objectType in {\em type} and the DER-code of objectValue
in {\em value} for objects of the form
\bc
{\small
\bvtab
PSEObject ::= \3 {\bf SEQUENCE} \{ \\
\5 objectType \3 OBJECT IDENTIFIER, \\
\5 objectValue \3 ANY DEFINED BY objectType \\
\3 \}
\evtab
}
\ec
It uses d\_PSEObject() to decode PSEObject (see E\_SEC(3X)).
It returns -1 if the object is not of this form, i.e. it cannot be decoded with d\_PSEObject().
Sec\_read\_PSE allocates the necessary memory for {\em type}\pf oid\_elements and {\em value}\pf octets.

\subsubsection{sec\_write}
\nm{3X}{sec\_write}{Write PSE object from octetstring}
\addtotoc{sec\_write\_PSE}
\label{sec_write}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_write} {\em (pse\_sel, content)} \\
PSESel *{\em pse\_sel}; \\
OctetString *{\em content};

RC {\bf sec\_write\_PSE} {\em (pse\_sel, type, value)} \\
PSESel *{\em pse\_sel}; \\
ObjId *type; \\
OctetString *{\em value};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em content}}
\pardescript  {Decrypted content of the object identified by {\em pse\_sel}\pf object.name.}

\parname  {{\em type}}
\pardescript  {Object identifier of the PSE object.}

\parname  {{\em value}}
\pardescript  {Decrypted content of the objectValue part of the object
               identified by {\em pse\_sel}\pf object.name.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
{\bf Sec\_write} writes octetstring {\em content} to the PSE object specified by
{\em pse\_sel}\pf object.name which has been previously opened by sec\_open.
In case of PIN protection the octetstring is
PIN encrypted before. Sec\_write overwrites the entire object.

In case of a SW-PSE, the object can be overwritten without being opened before. It is recommended, however,
to use sec\_open before writing an object to be compatible with applications using
a SC environment. \\ [1em]
{\bf Sec\_write\_PSE} encodes the given {\em type} and {\em value} into the DER-code of the
ASN.1 structure
\bc
{\small
\bvtab
PSEObject ::= \3 {\bf SEQUENCE} \{ \\
\5 objectType \3 OBJECT IDENTIFIER, \\
\5 objectValue \3 ANY DEFINED BY objectType \\
\3 \}
\evtab
}
\ec
and writes it to the PSE object specified by {\em pse\_sel}\pf object.name. It uses the encoding function
e\_PSEObject() (see E\_SEC(3X)). Sec\_write\_PSE overwrites the entire object.

\subsubsection{sec\_chpin}
\nm{3X}{sec\_chpin}{Change PIN}
\label{sec_chpin}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_chpin} {\em (pse\_sel, newpin)} \\
PSESel *{\em pse\_sel}; \\
char *{\em newpin};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE object.}

\parname  {{\em newpin}}
\pardescript  {New PIN.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
Sec\_chpin changes the PIN of the PSE object specified by {\em pse\_sel}.
As a result, the PSE object is decrypted with the old PIN (if any) and eventually
encrypted with the new PIN.
If {\em pse\_sel}\pf object.name is omitted, the PIN corresponding to the entire
PSE is changed. In this case, all PSE objects which have the global PIN (including the
Toc) are decrypted with the old key and encrypted with the new key.\\
The old PIN can be passed to sec\_chpin in {\em pse\_sel}\pf pin or {\em pse\_sel}\pf object.pin,
or the program will ask for it interactively.
If {\em newpin} is the NULL pointer, the program will also ask for the new PIN.

\subsubsection{sec\_read\_toc}
\nm{3X}{sec\_read\_toc}{Read the table of contents of the PSE}
\label{sec_read_toc}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
PSEToc *{\bf sec\_read\_toc} {\em (pse\_sel)} \\
PSESel *{\em pse\_sel};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE.}

\parname  {{\em Return Value}}
\pardescript  {Address of PSEToc or NULL.}
\hl{Description}
The table of contents (toc) of the PSE identified by {\em pse\_sel} is returned
as PSEToc. The necessary memory for PSEToc is provided by the called program.

\subsubsection{sec\_print\_toc}
\nm{3X}{sec\_read\_toc}{Print the table of contents of the PSE}
\label{sec_print_toc}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
RC {\bf sec\_print\_toc} {\em (pse\_sel)} \\
PSESel *{\em pse\_sel};
\hl{Parameter}
\parname  {{\em pse\_sel}}
\pardescript  {Structure which identifies the PSE.}

\parname  {{\em Return Value}}
\pardescript  {0 or -1.}
\hl{Description}
The table of contents (toc) of the PSE identified by {\em pse\_sel} is printed to stderr.

\subsection{ASN.1 encoding and Decoding Functions}
\nm{3X}{e\_SEC}{ASN.1 encoding and decoding functions for SEC-IF}
\label{Encoding-/Decoding-Secure}
\hl{Synopsis}
\#include $<$secure.h$>$ \\ [0.5cm]
OctetString *{\bf e\_KeyInfo} {\em (keyinfo)} \\
KeyInfo *{\em keyinfo};

KeyInfo *{\bf d\_KeyInfo} {\em (octetstring)} \\
OctetString *{\em octetstring};

RC {\bf d2\_KeyInfo} {\em (octetstring, keyinfo)} \\
OctetString *{\em octetstring}; \\
KeyInfo *{\em keyinfo};

OctetString *{\bf e\_EncryptedKey} {\em (encryptedkey)} \\
EncryptedKey *{\em encryptedkey};

EncryptedKey *{\bf d\_EncryptedKey} {\em (octetstring)} \\
OctetString *{\em octetstring};

RC {\bf d2\_EncryptedKey} {\em (octetstring, encryptedkey)} \\
OctetString *{\em octetstring}; \\
EncryptedKey *{\em encryptedkey};

OctetString *{\bf e\_Signature} {\em (signature)} \\
Signature *{\em signature};

Signature *{\bf d\_Signature} {\em (octetstring)} \\
OctetString *{\em octetstring};

RC {\bf d2\_Signature} {\em (octetstring, signature)} \\
OctetString *{\em octetstring}; \\
Signature *{\em signature};

BitString *{\bf e\_KeyBits} {\em (keybits)} \\
KeyBits *{\em keybits};

RC {\bf e2\_KeyBits} {\em (keybits, bitstring)} \\
KeyBits *{\em keybits}; \\
BitString *{\em bitstring};

KeyBits *{\bf d\_KeyBits} {\em (bitstring)} \\
BitString *{\em bitstring};

RC {\bf d2\_KeyBits} {\em (bitstring, keybits)} \\
BitString *{\em bitstring}; \\
KeyBits *{\em keybits};

OctetString *{\bf e\_AlgId} {\em (alg\_id)} \\
AlgId *{\em alg\_id};

AlgId *{\bf d\_AlgId} {\em (octetstring)} \\
OctetString *{\em octetstring};

RC {\bf d2\_AlgId} {\em (octetstring, alg\_id)} \\
OctetString *{\em octetstring}; \\
AlgId *{\em alg\_id};

OctetString *{\bf e\_PSEToc} {\em (pse\_toc)} \\
PSEToc *{\em pse\_toc};

PSEToc *{\bf d\_PSEToc} {\em (octetstring)} \\
OctetString *{\em octetstring};

OctetString *{\bf e\_PSEObject} {\em (objectType, objectValue)} \\
ObjId *{\em objectType}; \\
OctetString *{\em objectValue};

OctetString *{\bf d\_PSEObject} {\em (objectType, PSEObject)} \\
ObjId *{\em objectType}; \\
OctetString *{\em PSEObject};

\hl{Description}
The functions e\_* encode the given structure into an OctetString or BitString
respectively and return its address. Memory of the entire structure is provided
by the called program and can be released
by aux\_free\_OctetString() or aux\_free\_BitString().

The functions e2\_* encode the given structure into a given OctetString or BitString
respectively. Memory for the {\em octets} member or {\em bits} member of the given structure
is provided by the called program and can be released
using  free().

The functions d\_* decode the given OctetString into the indicated structure and return
a pointer to that structure. Memory of the entire structure is provided
by the called program and can be released by the respective aux\_free* function (see~\ref{aux_free}).

The functions d2\_* decode the given OctetString into the given structure.
Memory for those members of the given structure which are pointers is provided
by the called program and can be released using appropriate aux\_free* function (see~\ref{aux_free}).

OctetString or BitString consists of the ASN.1 encoding of the corresponding ASN.1 description of the C-structure (see SEC-PSE-OBJECTS(4) and AF-PSE-OBJECTS(4)).
\\ [1em]
The function e\_PSEObject encodes the given {\em objectType} and {\em objectValue} into the
DER-code of the ASN.1 structure
\bc
{\small
\bvtab
PSEObject ::= \3 {\bf SEQUENCE} \{ \\
\5 objectType \3 OBJECT IDENTIFIER, \\
\5 objectValue \3 ANY DEFINED BY objectType \\
\3 \}
\evtab
}
\ec
{\em ObjectValue} is the DER-code of an arbitrary ASN.1 structure.

The function d\_PSEObject extracts objectType and objectValue from the given
DER-code in {\em PSEObject} and returns objectType in {\em objectType} and
objectValue as return value. All necessary memory is allocated by the
called program.

\subsection{PSE-Objects}
\nm{4}{SEC-PSE-Objects}{PSE Objects of the SEC-Interface}
\label{sec-sw-cc}
\hl{Synopsis}
\#include $<$secure.h$>$

\hl{Description}
This section lists PSE objects needed by the sec\_* functions. Each object is presented in terms
of C-language structures as they are needed by the interface subroutines and
by the application programmer as well. The bit coding of the objects in the PSE
is given by applaying ASN.1 Basic Encoding Rules to the corresponding ASN.1 structures which
are additionally listed here.
Transformation between those two representations
is provided by the respective encoding/decoding functions e\_*(3X).

\subsubsection{Keys}
\hll{Keys}
On invocation of {\em sec\_encrypt}, {\em sec\_decrypt}, {\em sec\_sign}, {\em sec\_verify},
{\em sec\_get\_EncryptedKey}, {\em sec\_put\_EncryptedKey}, and {\em sec\_gen\_key}, necessary
keys can also be specified by reference to a PSE object (through parameter {\em key}). In this
case, the PSE object must be internally structured as X.509 (Annex G) defined
{\em SubjectPublicKeyInfo}. Seen from the C-language programmer, the PSE object
has the following structure:

{\small
\bvtab
\4      typedef struct KeyInfo \{ \\
\6              AlgId \3        *subjectAI; \\
\6              BitString \3    subjectkey; \\
\4      \} KeyInfo;  \\
\evtab
}

In case of RSA keys, the BitString {\em subjectkey} consists of the ASN.1-encoded representation of the
ASN.1 sequence {\em KeyBits} (see SEC-PSE-OBJECTS(4)).
It can be decoded with the function
{\em d\_KeyBits()} into the following C-structure:

{\small
\bvtab
\4      typedef struct KeyBits \{ \\
\6	        OctetString \4 part1; \\
\6      	OctetString \4 part2; \\
\4      \} KeyBits; \\
\evtab
}

Part1 and part2 contain the prime numbers $p$ and $q$ in case of secret keys, and the
modulus $m$ and the public exponent $e$ in case of public keys. The content of the
C-structure can be encoded into the ASN.1-encoded BitString with the function
{\em e\_KeyBits()}.

The corresponding ASN.1 notation which is the basis for the bit coding of the objects are:

{\small
\bvtab
\1 KeyInfo ::= \3 {\bf SEQUENCE} \{  \\
\5 algorithm         \2 AlgorithmIdentifier,    \\
\5 key               \2 BitString            \\
\5 -- -- \\
\5 -- -- the BitString of key    \\
\5 -- -- contains the ASN.1 encoding of a sequence of two \\
\5 -- -- INTEGERs part1 and part2, which are the RSA-modulus    \\
\5 -- -- n and the public RSA-exponent e in case of a public key,    \\
\5 -- -- or the two prime numbers $p$ and $q$ in case of a secret key.    \\
\5 -- -- \\
\5 -- -- SEQUENCE \{ \\
\5 -- -- \2       part1 INTEGER,   \\
\5 -- -- \2       part2 INTEGER  \\
\5 -- -- \} \\
\4 \}
\evtab
}

and

{\small
\bvtab
\1 KeyBits ::= \3 {\bf SEQUENCE} \{ \\
\5                 part1 \2  INTEGER    \\
\5                 part2 \2  INTEGER \\
\4 \}
\evtab
}

For explanation of the used names see SEC(5).

The OctetString which is stored on the PSE can be encoded or decoded with functions
{\em e\_KeyInfo} and {\em d\_KeyInfo} respectively.

\subsubsection{Toc}
\hll{Toc}
The table of contents (toc) of the PSE is maintained by those sec\_* functions which
handle the PSE. The C-structure of the toc given below is used only internally by these
functions. The application programmer does not need to handle them.

{\small
\bvtab
\4      typedef struct PSE\_Toc \{ \\
\6              char                \4 *owner; \\
\6              UTCTime             \4 *create; \\
\6              UTCTime             \4 *update; \\
\6		unsigned int        \4  status; \\
\6              struct PSE\_Objects \4 *obj; \\
\4      \} PSEToc;
\evtab
}
with:
{\small
\bvtab
\4      struct PSE\_Objects \{ \\
\6              char                \4 *name; \\
\6              UTCTime             \4 *create; \\
\6              UTCTime             \4 *update; \\
\6	        int                 \4  noOctets; \\
\6	        unsigned int        \4  status; \\
\6              struct PSE\_Objects \4 *next; \\
\4      \};
\evtab
}

UTCTime is defined in SEC(5).


\section{Getting started}

\subsection{What is OpenBDLM ?}
\label{S:OPENBDLMWHATIS}

OpenBDLM is a \MATLAB{} open-source software developed to use Bayesian Dynamic Linear Models for time series analysis with time steps in the order of one hour or higher.
OpenBDLM is capable of processing simultaneously several time series, enabling interpretation, monitoring and prediction over time.
OpenBDLM includes an anomaly detection tool which allows detecting abnormal behavior in a fully probabilistic framework.
In addition, OpenBDLM handles time series with missing data and non-uniform timestep vector.
OpenBDLM is available for download from GitHub at \url{https://github.com/CivML-PolyMtl/OpenBDLM}.\\

\noindent \textbf{Keywords}: time series analysis and forecasting, linear gaussian state-space models, time-series decomposition, anomaly detection, filtering, smoothing, bayesian analysis.

\subsection{Installing OpenBDLM}
\label{S:OPENBDLMINSTALLING}

The following instructions show how to download and setup OpenBDLM on your local machine for direct use, testing, and development purposes.
\subsubsection{Prerequisites}
\MATLAB{} (version 2016a or higher) installed on Mac OS X or Windows.\\

\noindent
The \MATLAB{}  \emph{Statistics and Machine Learning Toolbox} is required.

\subsubsection{Installation}
\begin{enumerate}
\item If an older OpenBDLM version is already installed, it is recommanded to remove from your \MATLAB{} path any previous OpenBDLM versions.
\item Download and extract the ZIP file from \url{https://github.com/CivML-PolyMtl/OpenBDLM} (or clone the git repository) in your working directory.
\item Add ``OpenBDLM-master'' folder and all its subfolders to your \MATLAB{}  path through one of the following two options:
\begin{itemize}
    \item Using the ``Set Path'' dialog box in \MATLAB{}, or
    \item By running  \lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!addpath! function from the \MATLAB{} command window
    \end{itemize}
\end{enumerate}

\subsection{Starting OpenBDLM}
\label{S:OPENBDLMGETTINGSTARTED}

\begin{itemize}
\item Set the current working directory to the folder ``OpenBDLM-master''
%\begin{center}
\item Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!OpenBDLM_main;!}, and press the key enter $\dlsh$.
%\end{center}
in the \MATLAB{} command line.
\end{itemize}
The OpenBDLM starting menu should appear on the \MATLAB{} command window (see Listing~\ref{LST:OpenBDLMStartingMenu}).
Type \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!Q!} in the command line, and press the key enter $\dlsh$ to quit the program.
%\begin{lstlisting}[ frame = single, basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}, linewidth=\linewidth] %, caption = OpenBDLM call ]%, label = LST:OpenBDLMmain, captionpos=b]
%[data, model, estimation, misc] = OpenBDLM_main();
%\end{lstlisting}
\begin{lstlisting}[ frame = single, basicstyle = \mlttfamily \scriptsize, caption = {OpenBDLM starting menu on  \MATLAB{} command window when calling \lstinline!OpenBDLM\_main;!}, label = LST:OpenBDLMStartingMenu ,  float =ht, linewidth=\linewidth, captionpos=b]
------------------------------------------------
     Starting OpenBDLM_V1.0
------------------------------------------------
            Time series analysis using
            Bayesian Dynamic Linear Models
------------------------------------------------
- Start a new project:

     *      Enter a configuration filename
     0   -> Interactive tool

- Type D to Delete project(s), V for Version control, Q to Quit.

     choice >>
\end{lstlisting}

\subsection{Demo}

In the \MATLAB{} command line, type
%\begin{lstlisting}[frame = single, basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}, caption = Run the OpenBDLM demo, label = LST:OpenBDLMdemo, captionpos=b, linewidth=\linewidth]
%run_DEMO.m
%\end{lstlisting}
%\begin{center}
\colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!run_DEMO;! }
%\end{center}
 followed by pressing the key enter $\dlsh$ to run a demo.
%\lstinline[basicstyle = \mlttfamily \small, backgroundcolor = \color{light-gray}]!run_DEMO.m! to run a little demo.
Some messages on the \MATLAB{} command window show that the program has started (see Listing~\ref{LST:MessageDemo}).
Several figures identical to those in Figures~\ref{fig:DataSummaryRawSynthetic}-\ref{fig:SYNTHETICOptimizedOptimized} should popup on the screen\footnote{The demo runs in batch mode following the example described in Section~\ref{S:EXAMPLESYNTHETICDATA}.}

\begin{lstlisting}[frame = single, basicstyle = \mlttfamily \scriptsize, caption = {Output on \MATLAB{} command window when running \lstinline!run_DEMO.m!}, linewidth=\linewidth, label=LST:MessageDemo, ,captionpos=b, float = h]
     Starting OpenBDLM_V1.0...
     Starting a new project...
     Building model...
     Simulating data...
     Plotting data...
     Saving database (binary format) ...
     Saving database (csv format) ...
     Saving project...
     Printing configuration file...
     Saving database (binary format) ...
     Saving project...
     Done ! See you soon !
\end{lstlisting}

\subsection{OpenBDLM main menu}
\label{S:OPENBDLMMAINMENU}

Once a project is loaded, the OpenBDLM main menu displays the list of actions which can be done (see Listing~\ref{LST:OpenBDLMMainMenu}).
The OpenBDLM main menu appears each time a selected action is done; until the user types \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!Q!} to save the project and quit the program.

%\begin{itemize}
%    \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!1!}: estimates the model parameters
%    \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!2!}: estimates the initial hidden states
%    \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!3!}: estimate the hidden states
%    \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!11!}: display the current model parameters values on the \MATLAB{} command line window and allows the user to modify the model parameters values
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!12!}: display the initial hidden states values on the \MATLAB{} command line window and allows the user to modify the initial hidden states values
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!13!}: display information about the current training period  on the \MATLAB{} command line window and allows the user to modify the training period
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!14!}: plot figures on the screen about the data in memory, the data availability, and the hidden states estimation results
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!15!}: display the content of the model matrices on the \MATLAB{} command line window at a specific time
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!16!}: create synthetic data from the current information in memory
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!17!}: export data and results as well as the figures in PNG, PDF and  \LaTeX{}   format
%     \item option  \colorbox{light-gray}{\lstinline[basicstyle = \mlttfamily \small ]!18!}: display the current options
%    \end{itemize}

\begin{lstlisting}[ frame = single, basicstyle = \mlttfamily \scriptsize, caption = { OpenBLDM main menu}, label = LST:OpenBDLMMainMenu,  float =h!, linewidth=\linewidth, captionpos=b]
---------------------------------------------
/    OpenBDLM main menu. Choose from
---------------------------------------------

     1  ->  Learn model parameters values
     2  ->  Estimate initial hidden states values
     3  ->  Estimate hidden states values

     11 ->  Display and modify current model parameter values
     12 ->  Display and modify current initial hidden states values
     13 ->  Display and modify current training period
     14 ->  Plots
     15 ->  Display model matrices
     16 ->  Create synthetic data
     17 ->  Export
     18 ->  Display current options in configuration file format

     Type Q to Save and Quit

     choice >>
\end{lstlisting}


\section{Conclusions}

In this study, we performed code-to-code verification on Moltres based on the
CNRS numerical benchmark \cite{tiberga_results_2020} for multi-physics,
\gls{MSR} simulation software. The benchmark assesses simulation
software through subproblems involving single-physics and coupled
neutronics/thermal-hydraulics.

The results showed that Moltres is mostly consistent with the other software
presented in the benchmark paper. The percentage discrepancies in the various
neutronics, velocity, and temperature quantities mostly fall within the same
order of magnitude. Minor deviations in the temperature in Steps 0.3 and 1.2
stem from the discontinuous velocity
boundaries on the top corners in the lid-driven cavity flow, while minor
deviations in the flux and delayed neutron source in Steps 0.2, 0.3, and 1.1
stem from the zeroth-order shape function approximation on the precursor
concentration. The results from Moltres agree closest to the TUD-S$_2$ model
from the benchmark, which implements the $S_2$ discrete ordinates method for
neutron transport.


\subsection{2\texorpdfstring{\textsuperscript{k}}{k}r analysis}\label{subsec:ld2kr}

Analysis performed with \(k\!=\!4\) and \(r\!=\!10\), for a total of \(2^4 \cdot
10 \!=\!160\) experiments.

The simulation configuration for this analysis, named ``LowDensity2kr'' can be
found in the \code{simulations.ini} file. The simulations have been run using
our \code{simulate.sh} script with the following command:
\begin{verbatim}
$ ./simulate.sh -s LowDensity -c LowDensity2kr
\end{verbatim}

First, we have verified that the range of values for the \code{maxCopies}
parameter (2--6) was fine. The analysis can be found in \code{histograms.ipynb}.

Then, the 2\textsuperscript{k}r analysis can be found in \code{2kr.ipynb}. We
will verify the assumptions of normality, independence and finite variance for
the residuals in \secref{subsec:ldassumptions}. Here we will discuss the
results.

\input{scenarios/low-density/2kr/coverage}
\input{scenarios/low-density/2kr/collisions}
\input{scenarios/low-density/2kr/messages}
\input{scenarios/low-density/2kr/time}


\documentclass{InsightArticle}

\usepackage[dvips]{graphicx}
\usepackage{float}
\usepackage[hang]{subfigure}

\usepackage[dvips,
bookmarks,
bookmarksopen,
backref,
colorlinks,linkcolor={blue},citecolor={blue},urlcolor={blue},
]{hyperref}

\title{A Patch-Based Inpainting Framework}

%
% NOTE: This is the last number of the "handle" URL that
% The Insight Journal assigns to your paper as part of the
% submission process. Please replace the number "1338" with
% the actual handle number that you get assigned.
%
\newcommand{\IJhandlerIDnumber}{3250}

% Increment the release number whenever significant changes are made.
% The author and/or editor can define 'significant' however they like.
\release{0.00}

% At minimum, give your name and an email address.  You can include a
% snail-mail address if you like.

\author{David Doria}
\authoraddress{Rensselaer Polytechnic Institute, Troy NY}

\begin{document}

\IJhandlefooter{\IJhandlerIDnumber}

\ifpdf
\else
   %
   % Commands for including Graphics when using latex
   %
   \DeclareGraphicsExtensions{.eps,.jpg,.gif,.tiff,.bmp,.png}
   \DeclareGraphicsRule{.jpg}{eps}{.jpg.bb}{`convert #1 eps:-}
   \DeclareGraphicsRule{.gif}{eps}{.gif.bb}{`convert #1 eps:-}
   \DeclareGraphicsRule{.tiff}{eps}{.tiff.bb}{`convert #1 eps:-}
   \DeclareGraphicsRule{.bmp}{eps}{.bmp.bb}{`convert #1 eps:-}
   \DeclareGraphicsRule{.png}{eps}{.png.bb}{`convert #1 eps:-}
\fi

\maketitle

\ifhtml
\chapter*{Front Matter\label{front}}
\fi

\begin{abstract}
\noindent
This document describes a system to fill a hole in an image by copying patches from elsewhere in the image. These patches should be a good continuation of the image outside the hole boundary into the hole. The implementation is very generic, allowing the develop to select or easily add new methods for the patch priority order, patch comparison function, and other parameters of the algorithm.

The ``basic'' algorithm is called ClassicalImpageInpainting and is based on the algorithm described in ``Object Removal by Exemplar-Based Inpainting'' (Criminisi et. al.).

The code is available here:
https://github.com/daviddoria/PatchBasedInpainting

\end{abstract}

\IJhandlenote{\IJhandlerIDnumber}

\tableofcontents
\section{Introduction}
This document describes a system to fill a hole in an image by copying patches from elsewhere in the image. These patches should be a good continuation of the hole boundary into the hole. The patch copying is done in an order which attempts to preserve linear structures in the image.

\section{Dependencies}
This code makes heavy use of multiple libraries:

\begin{itemize}
 \item VTK $>=$ 6.0
 \item ITK $>=$ 4.2
 \item Boost $>=$ 1.51
 \item CMake $>=$ 2.8.6
 \item Qt $>=$ 4.8
\end{itemize}

The code is also organized into git submodules. These are included if you clone with:
\begin{verbatim}
git clone --recursive https://github.com/daviddoria/PatchBasedInpainting.git
\end{verbatim}

or

\begin{verbatim}
git clone https://github.com/daviddoria/PatchBasedInpainting.git
git submodule update --init --recursive
\end{verbatim}

The required submodules are:

\begin{itemize}
 \item Mask - This submodule contains a set of classes for indicating a hole (to inpaint) in an image. It has functions to do things such as count the number of hole/valid pixels in a region, computed the gradient of a region without considering the values at masked pixels, etc.
 \item ITKHelpers (via Mask) - This submodule contains functions we commonly need to operate on ITK data structures. For example, it includes functions to extract the pixel values at specified pixel locations, extract channels of an image, etc.
 \item Helpers (via Mask\\ITKHelpers) - This submodule contains helper functions for the c++ language. It includes functions to do things such as writing a vector to a stream, check if a vector contains a specified value, compute the maximum of each channel of a vector container, etc. It also includes a Statistics class to compute averages, variances, etc. of multicomponent containers.
 \item BoostHelpers - This submodule allows us to do things such as inspect the values in a property map, output the values in a queue, etc.
 \item CMakeHelpers - This submodule allows us to use the submodule hierarchy in a much more straightforward fashion.
 \item ITKQtHelpers - This submodule allows us to convert back and forth between ITK and Qt data structures (images), which is needed to display patches from an itk::Image in a QGraphicsView.
 \item ITKVTKCamera - This submodule allows us to easily compensate for the difference in coordinate system between ITK and VTK.
 \item ITKVTKHelpers - This submodule allows us to convert back and forth between ITK and VTK data structures (images). For example, when we want to display an itk::Image in a vtkRenderer, we must first convert it to a vtkImageData.
 \item QtHelpers - This submodule provides functions to simplify some tasks for QImage (setting an image to a constant value, etc) and working with colors in Qt.
 \item VTKHelpers - This submodule contains many functions that we repeatedly need for VTK, including things like constructing a transparent image, outlining a region of an image, etc.
\end{itemize}

\section{Terminology}
Throughout this document, the ``source region'' is the portion of the image which is known (is not part of the hole) at the beginning. The ``target region'' is the current hole to be filled.

\section{Basic Algorithm Overview}
The inputs to the algorithm consist of an image and a binary mask the same size as the image. We use a custom Mask class to describe the hole (https://github.com/daviddoria/Mask). Throughout this paper, we have colored the region in the input image corresponding to the hole bright green. This color irrelevant - we have done this only to make it obvious to tell if any part of the hole remains after inpainting (it should not), and for easier debugging to ensure these pixels are not used in any part of the computation. In practice, the input image need not be modified.

\section{Algorithm Synthetic Demonstration}
Figure \ref{fig:SyntheticDemonstration} shows a synthetic demonstration of the algorithm. The image consists of a black region (top) and a gray region (bottom).  This simple example is used for testing because we know the result to expect - the dividing line between the black region and gray region should be continued smoothly.

\begin{figure}[H]
\centering
\subfigure[Image to be filled. The region to be filled is shown in bright green.]
  {
  \includegraphics[width=0.3\linewidth]{images/BlackWhite}
  \label{fig:SyntheticDemonstration:ExampleInputImage}
  }
\subfigure[The mask of the region to inpaint.]
  {
  \includegraphics[width=0.3\linewidth]{images/BlackWhiteMask}
  \label{fig:SyntheticDemonstration:ExampleInputMask}
  }
\subfigure[The result of the inpainting.]
  {
  \includegraphics[width=0.3\linewidth]{images/BlackWhiteResult}
  \label{fig:SyntheticDemonstration:ExampleInputOutput}
  }
\caption{Synthetic Demonstration}
\label{fig:SyntheticDemonstration}
\end{figure}

\section{Realistic Demonstration}
Figure \ref{fig:RealisticDemonstration} shows a real example of the algorithm. This result shows the typical quality of inpainting that the algorithm produces.

\begin{figure}[H]
\centering
\subfigure[Image to be filled. The region to be filled is shown in bright green.]
  {
  \includegraphics[width=0.3\linewidth]{images/Bungee}
  \label{fig:RealisticDemonstration:ExampleInputImage}
  }
\subfigure[The mask of the region to inpaint.]
  {
  \includegraphics[width=0.3\linewidth]{images/BungeeMask}
  \label{fig:RealisticDemonstration:ExampleInputMask}
  }
\subfigure[The result of the inpainting. This took about 30 seconds on a P4 3GHz processor with a 206x308 image and a patch radius = 5.]
  {
  \includegraphics[width=0.3\linewidth]{images/BungeeResult}
  \label{fig:RealisticDemonstration:ExampleInputOutput}
  }
\caption{Realistic Demonstration}
\label{fig:RealisticDemonstration}
\end{figure}

\section{Algorithm Structure}
An overview of the algorithm is:
\begin{itemize}
  \item Initialize:
    \begin{itemize}
      \item Read an image and a binary mask. Non-zero pixels in the mask describe the hole to fill.
      \item Set the size of the patches which will be copied. (Typically an 11x11 patch (patch radius = 5) is used).
      \item Locate all patches of the image which are completely inside the image and completely in the source region. These are stored as an $std::vector<itk::ImageRegion<2> >$ named SourcePatches.
    \end{itemize}

  \item Main loop:
  \begin{itemize}
    \item Compute the priority of every pixel on the hole boundary (see Section \ref{subsec:AlgorithmDetails:Priorities})
    \item Determine the boundary pixel with the highest priority. We will call this the target pixel. The region centered at the target pixel and the size of the patches is called the target patch.
    \item Find the source Pptch which best matches the portion of the target patch in the source region.
    \item Copy the corresponding portion of the source patch into the target region of the target patch.
    \item Repeat until the target region consists of zero pixels.
  \end{itemize}
\end{itemize}

%%%%%%%%%%%%%%%%%%
\section{Priority Functions}
\label{sec:PriorityFunctions}
The priority function is used to determine which target patch to fill next. We provide several such functions.

\subsection{PriorityCriminisi}
The priority term described in \cite{criminisi} is is given by the product of a Confidence term $C(p)$ and a Data term $D(p)$. This priority function attempts to both continue linear structures sooner rather than later, and fill patches where a larger number of the pixels in the patch are already filled.

\subsection{PriorityConfidence}
This priority function is the confidence term from the Criminisi priority function. Using this function essentially makes the algorithm fill patches from the outside of the hole and work its way inward.

\subsection{PriorityRandom}
This priority function selects a random target node to fill next. It is probably best to only use this ordering for debugging.

%%%%%%%%%%%%%%%%
\section{Patch Difference Functions}
\label{sec:PatchMatching}
Patch comparisons can be done between corresponding pixels or using non-pixel specific metrics. Several patch difference functions are provided.

\subsection{ImagePatchDifference}
This is the ``standard'' patch difference function that computes a sum of differences of corresponding pixels in two patches. It is templated on the comparison to be performed on each pair of corresponding pixels.

\subsection{GMHDifference}
This function computes the difference between the gradient magnitude histogram of the valid region of the target patch and the gradient magnitude histogram of the entire source patch.

%%%%%%%%%%%%%%%%
\section{Pixel Difference Functions}
\label{sec:PatchMatching}
The ImagePatchDifference class described above requires a function to compute the difference between pixels. Several such distance functions are provided, and the most notable ones are described here.

\subsection{SumSquaredPixelDifference (SSD)}
This function computes the sum of squared differences between every pixel in the valid region of the target patch and its corresponding pixel in the source patch. This is the standard difference function used in patch-based inpainting (e.g. \cite{criminisi}). This function is generic for any pixel type that has an operator[], but is specialized for pixels of type itk::CovariantVector. We also provide an explicitly unrolled version of this function, as since it is at the heart of the algorithm and the computational bottleneck, we have tried to do everything possible to ensure it runs as fast as possible.

\subsection{SumAbsolutePixelDifference (SAD)}
This function computes the sum of absolute differences between ND pixels. This function is generic for any pixel type that has an operator[], but is specialized for pixels of type itk::CovariantVector. We also provide an explicitly unrolled version of this function, as since it is at the heart of the algorithm and the computational bottleneck, we have tried to do everything possible to ensure it runs as fast as possible.

\subsection{WeightedSumSquaredPixelDifference}
This function computes a weighted sum of squared differences between ND pixels.

\subsection{HSVSSD}
The standard SSD function is acceptable if the image is represented in a color space (like RGB) where each channel is ``non-wrapping''. That is, the values in the upper range of the channel (255) should be significantly different from the values in the lower range of the channel (0). This is not the case with the H channel of the HSV color space, so we must treat its cyclic nature specially. In this class, we treat the S and V channels as ``standard'' channels, and use a special difference functor for the H channel that takes into account that we are measuring an angular distance and that wrapping over the upper range (1) back into the lower range (0) does not indicate an enormous difference, but rather we handle it correctly.

%%%%%%%%%%%%%%%
\section{Drivers}
As you will have noticed, the code is very heavily templated. A substantial amount of code is required to setup the objects to pass to the algorithm. To prevent code duplication when wanting to use the same algorithm in two contexts (for example, we may want a version of ClassicalImpageInpainting that displays its progress as it goes along and another that does not), we have separated this setup functionality into what we call a \emph{driver}. This allows us to separate the data preparation from this algorithm setup. For example, We have root/ClassicalImageInpainting.cpp and root/ClassicalImageInpaintingBasicViewer.cpp both of which use the ClassicalImpageInpainting driver.

%%%%%%%%%%%%%%%
\section{Interactivity}
We have drivers for each of our algorithms that are called by executables with matching names that are purely terminal programs. That is, they require no GUI context to be created (they do not display anything) and do not require any GUI input from the user (they do not ask questions using QDialog, etc). In these cases, the algorithm  (i.e. InpaintingAlgorithm) can be invoked as a normal function call.

However, in the case that we want to either display the intermediate progress (using BasicViewer) or prompt the user to do something like select a patch (for example, TopPatchesDialog), we must run the algorithm in a different thread so that the GUI stays responsive during the algorithm. As an example, refer to ClassicalImageInpaintingBasicViewer. Here the last line calls InpaintingAlgorithm, but is wrapped in a QtConcurrent::run call (which also requires boost::bind since the InpaintingAlgorithm is a function template). This starts the algorithm in a separate thread, and returns from the driver function to hit the app.exec() at the end of main() which triggers the GUI thread loop to start. Because of this behavior, and objects allocated on the stack (locals) in the driver function will immediately go out of scope, and nothing will work (everything will crash because the objects are no longer valid). To prevent this, we create everything and pass everything as a std::shared_ptr. The reference count of the shared pointers get increased as they are accepted by the Algorithm in the QtConcurrent::run() call, so they persist until they are no longer needed.

%%%%%%%%%%%%%%%
\section{Visitors}
In this code we heavily use the \emph{visitor pattern}. The idea is that the algorithm is specified as a very non-specific routine which can be filled in by the developer specifying the particular action that should be taken at each step in the algorithm. This really aligns code with the definition of ``algorithm'' that might be used outside of a programming context. As a simple example, consider the following algorithm:

\begin{verbatim}

void Algorithm(VisitorType visitor)
{
  while(not done)
  {
    currentObject = ...;
    visitor.Initialize(currentObject);
    visitor.Process(currentObject);
    visitor.Finalize(currentObject);
  }
}
\end{verbatim}

Here, as long as your visitor knows how to initialize, process, and finalize an object, it can be used with this algorithm. For example,

\begin{verbatim}

struct MyVisitor
{
  void Initialize(Object currentObject)
  {
    cout << "init.";
  }

  void Process(Object currentObject)
  {
    cout << "process.";
  }

  void Finalize(Object currentObject)
  {
    cout << "finalize.";
  }
};

...
MyVisitor myVisitor;
Algorithm(myVisitor);
...

\end{verbatim}

Will run the algorithm with the above dummy visitor, which will simply write out the name of each function as it is called.

\subsection{Acceptance Visitors}
These visitors, used with InpaintingAlgorithmWithVerification, take a source and target patch and determine if they are acceptable, usually by comparing some difference function to a threshold. For example, GMHAcceptanceVisitor uses the GMHDifference functor and then compares that value to a specified threshold. If the distance is below the threshold, the acceptance visitor returns true (acceptable), and otherwise returns false (not acceptable).

\subsection{Information Visitors}
\subsection{Descriptor Visitors}

%%%%%%%%%%%%%%%
\section{Utilities}
One of the main components of our inpainting algorithm is a priority queue that tracks which pixels are on the current hole boundary and maintains their priority. This problem is harder than it sounds. We have created an indirect priority queue that is a wrapper around boost::heap::binomial_heap. The trouble is that we often will have nodes in the queue that get invalidated (when the boundary changes, pixels currently in the queue are no longer valid boundary pixels), so we should not process those nodes when they get to the top of the queue. We also must provide a mechanism for changing the priority values associated with nodes that are already in the queue, which we do by storing those values in a property map and using a boost::indirect_cmp to sort the queue. The result is an easy to use queue that does what is expected of a boundary node queue for inpainting.

This directory also contains other helper functions (PatchHelpers) we need for some inpainting algorithms.
%%%%%%%%%%%%%%%
\section{Implementation Details}
\label{sec:ImplementationDetails}

\subsection{Isophotes}
An isophotes is simply a gradient vector rotated by 90 degrees. It indicates the direction of ``same-ness'' rather than the direction of maximum difference. There is a small trick, however, to computing the isophotes. We originally tried to compute the isophotes using the following procedure:

\begin{itemize}
 \item Convert the RGB image to a grayscale image.
 \item Blur the grayscale image.
 \item Compute the gradient using itkGradientImageFilter.
 \item Rotate the resulting vectors by 90 degrees.
 \item Keep only the values in the source region.
\end{itemize}

This procedure produces the gradient magnitude map shown in Figure \ref{fig:ErroneousGradient}.
\begin{figure}[H]
  \centering
  \includegraphics[width=0.3\linewidth]{images/ErroneousGradient}
  \caption{Result of naively computing the image gradient.}
  \label{fig:ErroneousGradient}
\end{figure}

The high values of the gradient magnitude surrounding the target region are very troublesome. The resulting gradient magnitude image using this technique is sensitive to the choice of the pixel values in the target region, which we actually want to be a completely arbitrary choice (it should not affect anything). More importantly, the gradient plays a large part in the computation of the pixel priorities, and this computation is greatly disturbed by these erroneous values. Simply ignoring these boundary isophotes is not an option because the isophotes on the boundary are exactly the ones that are used in the computation of the Data term. To fix this problem, we immediately dilate the mask specified by the user. This allows us to compute the isophotes as described above, but now we have image information on both sides of the hole boundary, leading to a valid gradient everywhere we need it to be. Figure \ref{fig:ErrorneousGradientCorrection} shows the procedure for fixing this problem.

\begin{figure}[H]
\centering
\subfigure[Image to be filled. The target region is shown in green.]
  {
  \includegraphics[width=0.3\linewidth]{images/BlackWhite}
  \label{fig:ErrorneousGradientCorrection:InputImage}
  }
\subfigure[The dilated mask.]
  {
  \includegraphics[width=0.3\linewidth]{images/BlackWhiteDilatedMask}
  \label{fig:ErrorneousGradientCorrection:InputDilated}
  }
\subfigure[The gradient magnitude with pixels in the new (enlarged) target region set to zero.]
  {
  \includegraphics[width=0.3\linewidth]{images/MaskedGradientMagnitude}
  \label{fig:ErrorneousGradientCorrection:Output}
  }
\caption{Procedure for fixing the erroneous gradient problem.}
\label{fig:ErrorneousGradientCorrection}
\end{figure}

As you can see, this gradient magnitude image is exactly what we would expect.

\subsection{Boundary Normals}
There are two things to be careful with when computing the boundary normals: computing the normals only on the one pixel thick boundary, and using the correct side of the masked region as the boundary.

\subsubsection{Computing boundary normals only on the one pixel thick boundary}
If we compute the normals directly on the binary mask, the set of resulting vectors are too discretized to be of use. Therefore, we first blur the mask. However, the gradient of the blurred mask results in non-zero vectors in the gradient image in many more pixels (a ``thick'' boundary) than the gradient of the original mask (a single pixel ``thin'' boundary). Therefore, we must mask the gradient of the blurred mask to keep only the pixels which would have been non-zero in the original mask gradient.

\subsubsection{Using the correct side of the masked region as the boundary}
There are two potential boundaries that can be extracted from a masked region - the ``inner'' boundary and the ``outer'' boundary. As shown in Figure \ref{fig:BoundarySide}, the inner boundary (red) is composed of pixels originally on the white (masked) side of the blob, and the outer boundary (green) is composed of pixels originally on the black (unmasked) side of the blob. It is important that we use the outer boundary, because we need the boundary to be defined at the same pixels that we have image information, which is only in the source (black/unmasked) region.

\begin{figure}[H]
\centering
\subfigure[The inner boundary.]
  {
  \includegraphics[width=0.3\linewidth]{images/BlackWhiteMask}
  \label{fig:BoundarySide:Mask}
  }
\subfigure[Outer boundary (green) and inner boundary (red).]
  {
  \includegraphics[width=0.3\linewidth]{images/BothBoundaries}
  \label{fig:BoundarySide:BothBoundaries}
  }
\caption{Inner vs Outer Boundary of a Region}
\label{fig:BoundarySide}
\end{figure}

%%%%%%%%%%%%%%%
\begin{thebibliography}{9}

	\bibitem{criminisi}
	  A. Criminisi, P. Perez, K. Toyama,
	  \emph{Object Removal by Exemplar-Based Inpainting}.
	  Computer Vision and Pattern Recognition 2003

\end{thebibliography}

\end{document}