# NeoGeographyToolkit/StereoPipeline

### Subversion checkout URL

You can clone with
or
.
Fetching contributors…

Cannot retrieve contributors at this time

348 lines (293 sloc) 14.512 kB
 \chapter{Development Plan} \label{ch:developmentplan} \begin{wrapfigure}{r}{0.3\textwidth} \vspace{-40pt} \begin{center} \includegraphics[width=0.25\textwidth]{graph/phoalgorithm} \end{center} \caption{Toolkit Outline} \vspace{-90pt} \end{wrapfigure} This provides a general outline of the Photometry Toolkit and how I currently envision it working. \section{Algorithm Outline} \begin{enumerate} \item Stereo Processing \item Initialize Photometry \begin{itemize} \item \textbf{Initialize DEMs and Blend} \hfill \\ This should be done with the already provided The DEM variance found is optional written here. \texttt{image2plate} and \texttt{platereduce}. \item \textbf{Ingest DRGs} \hfill \\ This involves thresholding the DRG for shadows and then solves for a grassfire weighting. The weighting and the masking are the same thing and should be stored inside the alpha channel for quick access. The masks used is optional written. \item \textbf{Seed Reflectance Images} \hfill \\ Load up camera models, and use SPICE to determine Sun's location. \item \textbf{Seed Exposure Time} \hfill \\ Somehow uses ratio of reflectance returns from previous step. \item \textbf{Seed Albedo Image} \hfill \\ Use this equation: $A_{ij}=\sum_{k}\frac{I^{k}_{ij}}{R^{k}_{ij}T^{k}}$ \end{itemize} \item Iterate Solution \begin{itemize} \item \textbf{Re-estimate Exposure} \hfill \\ $\hat{T^{k}} = T^{k}+\frac{\sum_{ij}(I^{k}_{ij}-T^{k}A_{ij}R^{k}_{ij})A_{ij}R^{k}_{ij}S^{k}_{ij}}{\sum_{ij}(A_{ij}R^{k}_{ij}S^k_{ij})^{2}}$ \item \textbf{Re-estimate Albedo} \hfill \\ $\hat{A_{ij}} = A_{ij}+\frac{\sum_{k}(I^k_{ij}-T^kA_{ij}R^k_{ij})T^kR^k_{ij}S^{k}_{ij}}{\sum_{k}(T^kR^k_{ij}S^k_{ij})^2}$ \item \textbf{Re-estimate DEM} \hfill \\ \emph{MAGIC!} \item \textbf{Re-calculate Reflectance} \hfill \\ Refer back to the cameras. \item \textbf{Calculate Error} \hfill \\ Error is used to determine if we're improving. $\epsilon=\sum_{k}\sum_{ij}((I^k_{ij}-A_{ij}T^kR^k_{ij})S^k_{ij})^2$ \end{itemize} \end{enumerate} \section{Content of Files} These files represent the results and working files from one session of the Photometry Toolkit. One project is inside a directory masquerading as file with extension \texttt{.ptk}. Here is a list of the possible contents contents. These files are only created one need. \begin{itemize} \item \textbf{photometrytk.dat} \hfill \\ This is a binary file written with google protobuf. This contains all the meta information about a PhoTK project. It is also what is served and modified as a service. The reason for this extra complexity is that multiple processes on multiple machines will be trying to access this file. \item \textbf{photometrytk.bak} \hfill \\ Back up file of \texttt{photometrytk.dat} that is written periodically in the case of a fault. Users can rename this file to \texttt{photometrytk.dat} if they think the original file is corrupt. \item \textbf{Albedo.plate} \hfill \\ Is a PixelGrayA platefile. This contains the final result of a mosaic. \item \textbf{DEM.plate} \hfill \\1 Is a PixelGrayA platefile. This contains the input DEM platefile. \emph{There is currently not a complete idea about how this is to be made or used by PhoTK.} \item \textbf{DEMVariance.plate} \hfill \\ Is a PixelGrayA platefile. \emph{This is still in design.} \item \textbf{DRG.plate} \hfill \\ Is a PixelGrayA platefile. It contains the input images. \item \textbf{Reflectance.plate} \hfill \\ Is a PixelGrayA platefile. \emph{This is still in design.} \item \textbf{Error.plate} \hfill \\ Is a PixelGrayA platefile. \emph{This is still in design.} \end{itemize} The platefiles Albedo, DEM, and DEMVariance are very similar and operate like normal plates do. These files are global image mosaics where the highest transaction ID represents the current working version. %% DEMVariance and Mask are both helpful plate files that are %% used for reporting; but they're not used again after the %% initialization step. The platefiles DRG, Reflectance, and Error are a little more tricky. They represent multiple K Cameras and their history. Their transaction IDs involve a little math so that $ID_{transaction} = 100*k+i$. Where $k$ is the camera number and $i$ is the iteration number. We provide only enough room for a hundred transactions. %% There's also one other file, the \emph{PhoFile} which contains most of %% the project information. If your familiar with the original Photometry %% module, this is the model params and the global params stitched %% together. I imagine this this file will probably use %% proto-buffers. Here's an outline of the contents. %% \begin{itemize} %% \item PhoFile \hfill \\ %% \begin{description} %% \item[Project Message] \hfill \\ %% This contains Datum along with various information transaction %% IDs. %% \item[Repeated Camera Message] \hfill \\ %% This contains the exposure time along with the Vector3 for the %% Sun Position and the Spacecraft Position. %% \end{description} %% \end{itemize} \section{Executables} %% \begin{wrapfigure}{r}{0.5\textwidth} %% \begin{center} %% \includegraphics[width=0.5\textwidth]{graph/exec_init} %% \end{center} %% \caption{Initialization Executables} %% \end{wrapfigure} Everything inside the Photometry Toolkit will hopefully fit inside 2 python scripts, \texttt{phoinit.py} and \texttt{phosolve.py}. As expected, \texttt{phoinit.py} creates all the files to start with. \texttt{phosolve.py} performs all the iterations. In the end when the user wants the results, they must perform \texttt{snapshot} or \texttt{plate2tile} to get the results. At this time of writing, only \texttt{phosolve.py} has been written. Everything is still largely manual and requires some thought by the user. The rest of this section outlines how to do some tasks that will hopefully add up to a full PhotometryTK session. \subsection{Creating a mosaicked DEM} This step is not currently used, but I thought it was worth noting as there are a few tricks. Mosaicking images in platefiles,is currently done with a utility called \texttt{platereduce}. It is good for calculating weighted averages or weighted variances. Calculating variances is mostly just useful for calculating DEM precision. If you are master of \texttt{snapshot}, you'll find that using \texttt{platereduce} to be very similar. I assume you have a working \texttt{index\_server} setup. The first steps are to apply \texttt{grassfirealpha} to all input images. This creates an alpha channel with feathered weights. The weights are highest value in the center of the image and lowest value near the edge. After that we'll enter all the alpha'd images into a single platefile. I'm using \texttt{xargs} to make this step multiprocess so I can utilize my entire machine. The \texttt{-P} option is the number of simultaneous processes to have running. Scale that setting to the appropriate value for your machine. \begin{verbatim} > echo *DEM.tif | xargs -n1 -P15 grassfirealpha > echo *grass.tif | xargs -n1 -P15 image2plate -o pf:///index/DEM_blend.plate \ --file tif -m equi \end{verbatim} Notice on \texttt{image2plate} that I set the output platefile to a TIF. This is important as the default option of PNG will shave bits on alpha'd values. I'm also using the 'equi' output option for an equirectangular projection. The default is to use a TOAST projection. We are now ready to run \texttt{platereduce}. The options \texttt{begin\_transaction} and \texttt{end\_transaction} specify the range of transaction IDs to read as input. The \texttt{transaction-id} option specify the output transaction ID to use. Reducing plate can be a very slow task, because of this we'll be doing it in parallel with multiple commands. This requires us to tell the \texttt{index\_server} by hand when we are starting a transaction and ending one. Notice how this is done if the following example. \begin{verbatim} > platereduce pf:///index/DEM_blend.plate -t 2000 --start "Averaging DEMs" > for i in {0 .. $(NUM_LEVELS)}; do platereduce --end_t 1999 -t 2000 pf:///index/DEM_blend.plate -f WeightedAvg & done > platereduce pf:///index/DEM_blend.plate -t 2000 --finish \end{verbatim} At this point the averaged DEM should be in transaction ID 2000 and it averaged all transaction IDs between 0 and 1999. \subsection{Creating a PhotometryTK project} Creating a project is done with the command \texttt{phoinitfile}. With this command you set what reflectance type you are solving for. You also specify which map projection to use for the project file. Current options are TOAST, Plate Equirectangular, and Polar. You also specify the number iterations to use for solving for the solution here. \emph{The number of iterations is not changeable after this step.} \begin{verbatim} > phoinitfile usgspolar -m polar --max 100 \end{verbatim} At this point we are ready to start serving the project out. This is accomplished with the utility called \texttt{ptk\_server}. The PTK server is both the platefile index server and PhoTK project file server. \emph{You will not be able to run another instance reliably of \texttt{index\_server} at the same time as \texttt{ptk\_server}.} It is possible that you might have an exchange name collision. \emph{Currently, PhoTK does not support the use of ZMQ urls.} \begin{verbatim} > ptk_server usgspolar.ptk --url pf:///polar \end{verbatim} The PTK server only serves one project at a time, therefor the first argument is the input project file \emph{(that is secretly a directory)}. The second argument specify the URL prefix we will be using for this project. A later points we will be needing our project's URL. It is the combination of the URL prefix and then the project file's name. For this example it is: \texttt{pf:///polar/usgspolar.ptk} At this point we are ready to start inserting our input images into the project. This is done with \texttt{phodrg2plate}. This is a clone of \texttt{image2plate} but it gets most of its settings from the served project file. Here's an example of me inserting files. \begin{verbatim} > echo *.tif | xargs -n1 -P15 phodrg2plate pf:///polar/usgspolar.ptk \end{verbatim} If you look inside the project file, you'll see that the platefile \texttt{DRG.plate} has been created. \subsection{Solving a PhotometryTK project} %%\begin{wrapfigure}{r}{0.4\textwidth} \begin{center} \includegraphics[width=0.4\textwidth]{graph/exec_solve} \end{center} %%\caption{Iteration Executables} %%\end{wrapfigure} Running the actually iterations of solving is pretty easy since it is currently hidden away in a python script. The file script \texttt{phosolve.py} does all the steps of re-estimating exposure and updating albedo. In the future, calculating reflectance and shape-from-shading will be inserted as optional steps in this file. \begin{verbatim} > phosolve.py --threads 15 --level 9 --iter 100 pf:///polar/usgspolar.ptk \end{verbatim} The level option is just what level of the image pyramid we wish to perform our calculations. The lower the number \emph{(the higher up the pyramid)} will increase the speed at which things are processed. However there is more likely a chance of error. I usually run my sessions at about two thirds down the pyramid. After this step is completed you will find that \texttt{Albedo.plate} has been created in your project file. Viewing it can be tricky. \emph{(In my example, the Albedo's url will be pf:///polar\_index/Albedo.plate.)} However you will find that only one level of the pyramid has actually be populated. That makes it difficult to locate that solution. Things are easier for the viewer if you mipmap the solution up the pyramid. \begin{verbatim} > pmipmap --level 9 --threads 15 pf:///polar_index/Albedo.plate \end{verbatim} Viewing should now be much easier in VWV. \begin{verbatim} > vwv pf:///polar_index/Albedo.plate \end{verbatim} \subsection{Using ZMQ instead} The above examples are using RabbitMQ for the message passing. I've since become a fan of using ZeroMQ as it doesn't require a server to be started. Remember that RabbitMQ has an erlang executable running in the background that occasionally crashes after a length of time. So here's the above examples rewritten to show how to use ZMQ, however not everything works at this point in time. \begin{verbatim} > phoinitfile secret_base -m polar --max 100 > ptk_server secret_base.ptk --url zmq://*.5566 In new terminal: > parallel -j -2 phodrg2plate zmq://localhost:5566/secret_base.ptk ::: *.tif > phoitalbedo zmq://localhost:5566/secret_base.ptk -l 10 \end{verbatim} Unforunately, \texttt{vwv} across ZMQ doesn't seem to be working at all. For the time being I just kill the \texttt{ptk\_server} and run \texttt{vwv} on the platefile directly. \subsection{Running once at high resolution and extracting result} Meh. %% \subsection{An example run of PhotometryTK} %% Eventually the the python scripts should negate the need for %% this. Here are the actual executables called and the settings to %% use. Delete this section some time in the future. %% \begin{verbatim} %% > sudo$(START UP AMQP COMMAND) %% > (in a different terminal) index_server $(PROJECT DIR) %% > cd$(DEM_DIR) %% > ls *DEM.tif | xargs -n 1 -P 10 grassfirealpha --nodata -10000 %% > ls *grass.tif | xargs -n 1 -P 10 image2plate -o %% pf://index/DEM_blend.plate --file tif -m equi %% > for i in {0..$(NUM LEVELS)}; do platereduce --end_t 1999 -t 2000 %% pf://index/DEM_blend.plate -l$i & done %% > plate2plate -o pf://index/DEM.plate -i pf://index/DEM_blend.plate %% --filter identity --bottom 10 --skim %% > (in other terminal, kill index_server) %% > rm -rf DEM_blend.plate %% > (in other terminal, restart index_server) %% > phoinitfile debug_apollo %% > // Below can be ran in parallel %% > echo *.tif | xargs -n1 echo | %% xargs -n1 -P10 phodrg2plate pf://ptk/project.ptk %% > echo {0..9} | xargs -n1 echo | %% xargs -n1 -P10 -I{} phoitalbedo -j {} -n 10 pf://ptk/project.ptk %% > mipmap pf://index/Albedo.plate %% \end{verbatim}
Something went wrong with that request. Please try again.