==================================
The Rolling Hough Transform (RHT)
==================================

This is the Rolling Hough Transform, described in Clark, Peek, Putman 2014 (arXiv:1312.1338).

Included is a modified RHT which distinguishes between pixels located at theta, and at theta+pi, in polar coordinates centered on any given image pixel. This is achieved by searching along radii with twice the dtheta of the diameters searched in the RHT. This Transform is still in development.

==================================
Requirements (Python 2.7 Only)
==================================
from __future__ import division #Must be first line of code in the file
from astropy.io import fits
import scipy.ndimage
import math
import os
import sys
import string
import tempfile 
import shutil
import time 
import fnmatch
import matplotlib.pyplot as plt
import numpy as np

==================================
Instructions For Use (Python)
==================================
1. Ensure your Python 2.7 Environment is as up-to-date as possible and contains the required imports. The code has been tested to run on both Windows and Mac computers successfully, without modification:

>>>python --version //Currently Supports 2.7.5

2. Ensure you are able to import the package:

>>>import rht 

3. Run the RHT for individual files or directories, given a number of parameters. Output will be placed alongside the input files in the .fits format, with a record of the parametrs that created it:

>>>rht.main() #Runs the RHT, after asking for user input, with default parameters

>>>rht.main('filepath') #Runs the RHT for a given image or within a given directory with default parameters

>>>rht.main('filepath', flag=value, param=value) #Runs with some flag set to a boolean and some param set to a number

4. Explanation of rht.main() Flags and Parameters
   Flags: 
     display=True  #Ouput is to be Displayed
     force=True    #Exisitng output is to be Forcefully overwritten
     orig=True     #The DOUBLE SIDED RHT is to be used
     new=True      #The SINGLE SIDED RHT is to be used
   Params:
     wlen=value  #Sets window diameter
     smr=value   #Sets smoothing radius
     frac=value  #Sets theta power threshold
     orig=value #Whether the DOUBLE SIDED RHT is used

5. Displaying the results of previously Interpreted RHT data (#TODO_Deprecated)

>>>rht.viewer('filepath') #Will first call rht.interpret('filepath') if necessary
>>>rht.viewer('filepath', force=True) #Will ALWAYS call rht.interpret('filepath', force=True) first

==================================
Instructions For Use (Terminal)
==================================
Command Line Argument Format:
 >>>python rht.py arg1 arg2 ... argn 

NO ARGS:
 Displays README and exits
 >>>python rht.py

SINGLE ARGS:
 pathname ==> Input file or directory to run the Default RHT on
 >>>python rht.py dirname/filename.fits
  
 'help', '-help', 'h', '-h' ==> Displays this message
 >>>python rht.py -h

 'params', 'param', 'p', '-p', '-params', '-param' ==> Displays Default Params
 >>>python rht.py param
 
MULTIPLE ARGS:
 1st ==> Input file or directory to run the RHT on
 2nd:nth ==> Named inputs controlling parameters and flags
  Flags: 
  'd', '-d', 'display', '-display'  ==> Ouput is to be Displayed
  'f', '-f', 'force', '-force'      ==> Exisitng output is to be Forcefully overwritten
  'o', 'orig', '-o', '-orig'        ==> The DOUBLE SIDED RHT is to be used
  'n', 'new', '-n', '-new'          ==> The SINGLE SIDED RHT is to be used
  Params:
  'w', 'wlen', '-w', '-wlen' =value ==> Sets window diameter
  's', 'smr', '-s', '-smr'   =value ==> Sets smoothing radius
  'f', 'frac', '-f', '-frac' =value ==> Sets theta power threshold
  'o', 'orig', '-o', '-orig' =value ==> Whether the DOUBLE SIDED RHT is used

==================================
Directory Structure
==================================
RHT:
|__This README

|__The rht.py python module, based on fastrht.py for performing the Hough Transform

|__Batches of Image files:

   |__Each image and their computed _xyt??.fits outputs

|__Git version control information

==================================
Other Information
==================================
|__input:

   |__Manageable .fits, .npy, etc image files
   |__REMEMBER THAT O(RHT) ~ wlen^3, where wlen is the kernel diameter

|__output:
   |__i,j coordinates in image space, and the theta powers at that coordinate 
   |__Backprojection of theta power onto orignal image coordinates


==================================
Attribution
==================================
#This is the Rolling Hough Transform, described in Clark, Peek, Putman 2014 (arXiv:1312.1338).
#Modifications to the RHT have been made by Lowell Schudel, les2185@columbia.edu, CC'16.