%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Copyright (C) 2014-2016, New York University.
%% Copyright (C) 2011-2014, NYU-Poly.
%% Copyright (C) 2006-2011, University of Utah.
%% All rights reserved.
%% Contact: contact@vistrails.org
%%
%% This file is part of VisTrails.
%%
%% "Redistribution and use in source and binary forms, with or without
%% modification, are permitted provided that the following conditions are met:
%%
%%  - Redistributions of source code must retain the above copyright notice,
%%    this list of conditions and the following disclaimer.
%%  - Redistributions in binary form must reproduce the above copyright
%%    notice, this list of conditions and the following disclaimer in the
%%    documentation and/or other materials provided with the distribution.
%%  - Neither the name of the New York University nor the names of its
%%    contributors may be used to endorse or promote products derived from
%%    this software without specific prior written permission.
%%
%% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
%% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
%% THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
%% PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
%% CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
%% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
%% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
%% OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
%% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
%% OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
%% ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass{article}

%% This file illustrates how to embed images of vistrails published on
%% crowdLabs.  Please refer to
%% http://www.crowdlabs.org/site_media/static/user_docs/vistrails_usage.html
%% for instructions on how to publish workflows to crowdLabs and to
%% http://www.crowdlabs.org/site_media/static/user_docs/embedding.html for
%% more details about how to use this extension.

%% This is crowdlabs main package
\usepackage{crowdlabs}
\usepackage{subfigure}

%% The crowdlabs extension requires python. If your python is not in the path,
%% uncomment the line below and edit with the path to your python executable
%\renewcommand{\pythonpath}{C:/Python27/python.exe}

%% You need to enable the crowdlabs package. Make sure crowdlabs.sty is located
%% in the same directory as the .tex file in which you want to embed the images.

%% If crowdlabs you are using is not on crowdlabs.org, 
%% uncomment the line below and configure it with the current server
%\renewcommand{\urlcrowdlabs}{http://yourcrowdlabsserver.com}

\title{Embedding workflows in \LaTeX\ using crowdLabs}
\author{The VisTrails Team}
\begin{document}
\maketitle
\begin{abstract}
This article shows how to embed images from workflows stored on
\url{www.crowdlabs.org} in a \LaTeX\ document. The images can be
workflow results, workflow graphs or VisTrails' history trees.
\end{abstract}

\begin{figure}[th]
\begin{center}
\crowdlabs[wfid=1054,
buildalways=false]{width=0.50\linewidth}
\end{center}
\vspace{-.5cm}
\caption{Embedding the image generated by the Isosurface workflow. Click on the image to see the details on \url{www.crowdlabs.org}.}
\label{fig:isosurface}
\end{figure}

\section{Introduction}
%% Please refer to \\
%%  http://www.crowdlabs.org/site\_media/static/user\_docs/vistrails\_usage.html
%%  \\
%% for instructions on how to publish workflows on crowdLabs  and to \\
%%  http://www.crowdlabs.org/site\_media/static/user\_docs/embedding.html \\
%% for more details about how to use this extension.

After uploading your workflows to crowdLabs\footnote{Please visit
\url{http://www.crowdlabs.org/site_media/static/user_docs/vistrails_usage.html}
if you need instructions on how to publish workflows to crowdLabs}, you need the following requirements in order to embed the workflows in the \LaTeX\ file:
\begin{itemize}
\item Python (\url{www.python.org})
\item the file \textsf{crowdlabs.sty}
\item and the file \textsf{includecrowdlabs.py} 
\end{itemize} 

Both \textsf{crowdlabs.sty} and \textsf{includecrowdlabs.py} are
located in the same directory as this document and they should be
copied to the same folder that your main document is located.

\subsection{Preparing the \LaTeX\ document}

After copying the files, you need to configure your document.In the
preamble of the \LaTeX\ file add the crowdlabs package: 
\begin{verbatim}
   \usepackage{crowdlabs}
\end{verbatim}

As we mentioned before, the crowdLabs package requires Python to
run. If the python executable is not accessible in the PATH, you will
need to set the \texttt{\textbackslash pythonpath} command with the correct path for your environment:
 
\begin{verbatim}
   \renewcommand{\pythonpath}{C:/Python27/python.exe}
\end{verbatim}

Also, by default, \url{crowdlabs.org} will be used as the main server, but
you can use your own crowdLabs server setting the \texttt{\textbackslash urlcrowdlabs} command: 
\begin{verbatim}
   \renewcommand{\urlcrowdlabs}{http://yourcrowdlabsserver.com}
\end{verbatim}

\section{Embedding workflows}
If you go to \url{crowdlabs.org} and visit the details page of the
workflow you would like to embed, you will see a tab just below the
resulting image, named \textsf{Embed this Workflow}. Clicking on it,
will display snippets you can use to embed that particular workflow in
different types of documents. So copy the text displayed in the
\textsf{In LaTex} box. For example, we will embed the image produced
by the workflow
\textbf{Isosurface}\footnote{\url{http://www.crowdlabs.org/vistrails/workflows/details/1054/}}.

We copied and pasted the following text into this document:
\begin{verbatim}
  \crowdlabs[wfid=1054,
   buildalways=false]{}
\end{verbatim}

And it generated the image in Figure~\ref{fig:isosurface}. Clicking on the image will take you to that workflow's details page.

\subsection{Controlling the appearance of the image}
In the \texttt{\textbackslash crowdlabs} command, there are different options to control how the workflow will be embedded. The example above is the simplest way to embed the results of a workflow. To control the size of the image, you write between the curly braces, the options you would normally send to the  \texttt{\textbackslash includegraphics} command. For example:  

\begin{verbatim}
  \crowdlabs[wfid=1054,
   buildalways=false]{width=0.45\linewidth}
\end{verbatim}

You can also use the \texttt{\textbackslash crowdlabs} command together with the \texttt{\textbackslash subfigure} command:
\begin{verbatim}
  \begin{figure}[t]
     \centering{
        \subfigure[Isosurface]{\label{fig:isosurface2}  
           \crowdlabs[wfid=1054,
             buildalways=false]{width=0.35\linewidth}}
        \subfigure[Volume Rendering]{\label{fig:vr}  
            \crowdlabs[wfid=1046,
             buildalways=false]{width=0.35\linewidth}} }
  \end{figure}
\end{verbatim}

\begin{figure}[t]
\centering{
\mbox{\subfigure[Isosurface]
 {\label{fig:isosurface2}  
  \crowdlabs[wfid=1054,
   buildalways=false]{width=0.35\linewidth} 
 }
\subfigure[Volume Rendering]
 {\label{fig:vr}  
  \crowdlabs[wfid=1046,
  buildalways=false]{width=0.35\linewidth}
 }}
}
\caption{Using the \texttt{\textbackslash crowdlabs} command with the \texttt{\textbackslash subfigure} command.}
\label{fig:subfigure}
\end{figure}

\subsection{Caching images}
The \textsf{buildalways} option controls whether the images should be cached or not. \textsf{buildalways=false} means that the image will be downloaded only once and every time that you compile your \LaTeX\ document, the image downloaded will be reused. On the other hand, if you set \textsf{buildalways=true}, the image will be downloaded from crowdLabs every time the document is compiled. The images are kept inside the \textsf{crowdlabs\_images} folder.

\subsection{Embedding the workflow graph}
To embed the workflow graph, just use the \textsf{showworkflow} option inside the \texttt{\textbackslash crowdlabs} command. For example, this is the command to embed the workflow graph that generated Figure~\ref{fig:isosurface}:\\

\begin{verbatim}
  \crowdlabs[wfid=1054,
   showworkflow,
   buildalways=false]{width=0.60\linewidth}
\end{verbatim}

And it will generate Figure~\ref{fig:workflow}.
\begin{figure}[th]
\begin{center}
\crowdlabs[wfid=1054,
showworkflow,
pdf, % use the pdf key to generate in pdf
buildalways=false]{width=0.60\linewidth}
\end{center}
\vspace{-.5cm}
\caption{Isosurface workflow that generated Figure~\ref{fig:isosurface}}
\label{fig:workflow}
\end{figure}

\subsection{Embedding figures in the PDF format}
If you want to embed the figure in the PDF format, use the \textsf{pdf} option:

\begin{verbatim}
  \crowdlabs[wfid=1054,
   showworkflow,
   pdf,
   buildalways=false]{width=0.60\linewidth}
\end{verbatim}


\subsection{Embedding VisTrails' history trees}

It is also possible to embed the history tree of a Vistrail. To do that, use the \textsf{vtid=<...>} instead of the \textsf{wfid=<...>} option.

\begin{verbatim}
  \crowdlabs[vtid=209,
  buildalways=false]{width=0.90\linewidth}    
\end{verbatim}

To get the \textsf{vtid} of a vistrail, just visit the page of the vistrail in crowdLabs and copy the number that appears in the address bar at the end of the url:

\begin{verbatim}
    http://www.crowdlabs.org/vistrails/details/209/
\end{verbatim}

So for the address above, 209 is the \textsf{vtid} of the vistrail \textbf{terminator-latex}.

The command above generates the image in Figure~\ref{fig:tree}.
\begin{figure}[th]
\begin{center}
\crowdlabs[vtid=209,
% pdf, %uncomment this for using the pdf format
buildalways=false]{width=0.90\linewidth}
\end{center}
\vspace{-.5cm}
\caption{History tree containing the workflows used in this document}
\label{fig:tree}
\end{figure}

The \textsf{pdf} option can also be used if you want to embed the tree in PDF format.

\end{document}