%This document is distributed under the terms of the GNU Free Documentation
%License. Please, see http://www.gnu.org/licenses/
\documentclass[10pt,a4paper]{article}
\usepackage{tocbibind}
\usepackage{hyperref}
\hypersetup{colorlinks,citecolor=red,linkcolor=red,urlcolor=red}

\newcommand{\octclip}{\texttt{OctCLIP}}
\newcommand{\octave}{GNU Octave}

\title{Clipping polygons in \octave\footnote{This document is distributed
       under the terms of the GNU Free Documentation License. Please, see
       \url{http://www.gnu.org/licenses/}}}
\author{Jos\'e Luis Garc\'ia Pallero\footnote{ETSI en Topograf\'ia, Geodesia y
        Cartograf\'ia, Universidad Polit\'ecnica de Madrid.
        \texttt{jlg.pallero@upm.es}, \texttt{jgpallero@gmail.com}}}
\date{November 7, 2022 (version 2.0.3)\\
      March 25, 2022 (version 2.0.2)\\
      May 16, 2020 (version 2.0.1)\\
      May 11, 2020 (version 2.0.0)\\
      May 9, 2020 (version 1.1.0)\\
      May 9, 2020 (version 1.0.9)\\
      June 16, 2015 (version 1.0.8)\\
      April 28, 2015 (version 1.0.7)\\
      February 13, 2015 (version 1.0.6)\\
      June 20, 2013 (version 1.0.5)\\
      October 1, 2012 (version 1.0.2)\\
      November 21, 2011 (version 1.0.1)\\
      May 24, 2011 (version 1.0.0)}

\begin{document}
\maketitle
% \tableofcontents

\begin{abstract}
This is a small introduction to using the \octclip{} package. In this text, you
can overview the basic usage of the functions in
\octave\footnote{\url{http://www.octave.org}}. If you need a detailed
description about the Greiner-Hormann implemented algorithm, please read
\cite{greiner1998} and visit \url{http://davis.wpi.edu/~matt/courses/clipping/}.
\end{abstract}

\section{Overview}

The \octclip{} package allows you to perform boolean operations (intersection,
union, difference and exclusive or) between two polygons in \octave{} using the
Greiner-Hormann algorithm as presented in \cite{greiner1998}. This method is an
efficient algorithm for clipping arbitrary 2D polygons. The algorithm can handle
arbitrary closed polygons included the cases when the subject and/or clipper
polygons contain self-intersections.

\section{Installation}

As most of \octave{} packages, \octclip{} installation consists in compiling the
C++ kernel sources, link them against \octave{} library to generate
\texttt{*.oct} functions and copy this \texttt{*.oct} executables and other
\texttt{*.m} functions into a working directory.

The automagic procedure can be easily done by running the command:

\begin{verbatim}
octave:1> pkg install octclip-x.x.x.tar.gz
\end{verbatim}
where \texttt{x.x.x} is the version number.

After that, the functions and documentation are installed in your machine and
you are ready for use the package.

\section{\octave{} functions}

Two types of functions are programmed for \octave: one \texttt{*.oct} function
and one \texttt{*.m} function.

\subsection{\texttt{*.oct} function}
\label{op-of}

This function are linked with the C code that actually make the computations.
You can use it, but is no recommended because the input arguments are more
strict than \texttt{*.m} functions and don't check for some errors.

The function is:
\begin{itemize}
\item \texttt{\_oc\_polybool}: Performs boolean operation between two polygons.
\end{itemize}

\subsection{\texttt{*.m} function}

This function makes the computations by calling the \texttt{*.oct} function. You
must call this function because you can use different number of input arguments
and checking of input arguments is performed.

The function is the same as in section \ref{op-of} (without the \texttt{\_} at
the beginning of the name):
\begin{itemize}
\item \texttt{oc\_polybool}: Performs boolean operation between two polygons
      by calling the \texttt{\_oc\_polybool}.
\end{itemize}

\texttt{oc\_polybool} includes too some demonstration code in order to test the
functionality of the functions. The demo code can be executed as:
\begin{verbatim}
octave:1> demo oc_polybool
\end{verbatim}

\subsection{Error handling}

\texttt{*.oct} and \texttt{*.m} functions can emit errors, some due to errors
with input arguments and other due to errors in functions from the
C\footnote{The algorithm is internally implemented in C (C99 standard).} code.

Errors due to wrong input arguments (data types, dimensions, etc.) can be only
given for \texttt{*.m} function and this is the reason because the use of this
function is recommended. In this case, the execution is aborted and nothing is
stored in output arguments.

The \texttt{*.oct} function can emit errors due to wrong number of input
arguments, wrong value of the operation identifier and internal errors of memory
allocation.

\section{Caveats of Greiner-Hormann algorithm}

To do.

\section{Notes}

Apart from \url{http://octave.sourceforge.net/octclip/index.html}, an up to date
version of \octclip{} can be downloaded from
\url{https://bitbucket.org/jgpallero/octclip/}.

\begin{thebibliography}{9}
\bibitem{eat-om} \textsc{Eaton}, John W.; \textsc{Bateman}, David;
                 \textsc{Hauberg}, S\o{}ren; and \textsc{Wehbring}, Rik;
                 GNU Octave. A high-level interactive language for numerical
                 computations; Edition 5 for Octave version 5.2.0, January 2020;
                 \url{https://www.gnu.org/software/octave/octave.pdf};
                 Permanently updated at
                 \url{https://www.gnu.org/software/octave/support.html}.

\bibitem{greiner1998} \textsc{Greiner}, G\"unter, and \textsc{Hormann}, Kai;
                      \textit{Efficient clipping of arbitrary polygons}; ACM
                      Transactions on Graphics; Volume 17(2), April 1998;
                      Pages 71--83. There is a web link with some example code
                      at \url{http://davis.wpi.edu/~matt/courses/clipping/}.
\end{thebibliography}

\end{document}

%Copyright (C) 2011-2020, José Luis García Pallero, <jgpallero@gmail.com>
%This document is distributed under the terms of the GNU Free Documentation
%License. Please, see http://www.gnu.org/licenses/
