TODO: Documentation functions has been completed

TODO.md

@@ -7,7 +7,7 @@
 
 ## To Do:
 
-* Document Functions
+* Document Functions (COMPLETE)
 * Change from `global` to pass around
 * Change `save_image()` to `output_image`
-* 
+* Move all the image stuff over to it's own

dataLoad.py

@@ -31,17 +31,20 @@ sess = requests.Session()
 head = {'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36'}
 sess.headers.update(head)
 
-ON = 'X'
-OFF = '.'
-DIR = 'data'
+ON = 'X'      # Dark pixel in an image
+OFF = '.'     # Light pixel in an image
+DIR = 'data'  # Data directory name, do we really need this? Is it really going to change?
 
-INTENSITY = 75
+INTENSITY = 75 # How bright does something have to be to trigger it being a dark or light pixel?
+# Looks like around 75 removes the extra stuff that s0urce.io does to prevent it from being just matching images.
 
+# Globals, Yuck!
 im = ''
 pix = [0, 0]
 size = [0, 0]
 pal = ''
 
+# Check the environment, do we have all that we need?
 if not os.path.exists('in'):
     os.mkdir('in')
 
@@ -54,20 +57,32 @@ def download(howhard, index):
     Download an image based upon how hard it is.
 
     You print out the return value.  Are you returning anything useful??
+    (Ah, yeah I could just have it print out the status code when there is a error,
+     Which would get rid of the need for it to return anything)
     """
     r = sess.get(f'http://s0urce.io/client/img/word/{howhard}/{index}')
     if(r.status_code == 200):
         with open(f'in/{howhard}_{index}.png', 'wb') as f:
             f.write(r.content)
-        return f'{howhard}_{index}.png ' + str(r.status_code)
-    return r.status_code
+    # We did not get a 200 Okay, log this... Hmm maybe we need to make a log file?
+    print( f'{howhard}_{index}.png ' + str(r.status_code) )
 
 def img_point(x, y):
-        global pix
-        return pix[x, y]
+    global pix
+    """
+    img_point, returns a pixel of an image,
+    given the x and y on the image.
+    """
+    return pix[x, y]
 
 def img_avg(x, y):
     global im, pal
+    """
+    img_avg, returns the average brightness 0-255,
+    given the x and y on the image calls img_point,
+    to get the individual rgb values to calculate,
+    brightness.
+    """
     rgb = img_point(x,y)
     if(im.mode == 'P'):
         rgb = pal[rgb*3:(rgb+1)*3]
@@ -79,11 +94,31 @@ def img_avg(x, y):
 
 def is_set(x, y):
     global INTENSITY
+    """
+    is_set, returns True or False of calculating,
+    the brightness of the given point on a image,
+    compared to given intensity.
+    
+    True means the brightness at the given x and y,
+    is Less Than which means its dark.
+    
+    False means the brightness at the given x and y,
+    is Greater Than which means its bright.
+    """
     avg = img_avg(x,y)
     return (avg < INTENSITY)
 
 def scan_img():
     global sx, sy, ex, ey, total
+    """
+    scan_img, looks at a image and looks for dark pixels,
+    if it is a dark pixel record the number and resize the,
+    returned values to show where the most dark pixels on the,
+    image are located.
+    
+    given image size.
+    returns start x, y and end x, y and total number of dark pixels.
+    """
     total = 0
     sx = size[0]; ex = 0
     sy = size[1]; ey = 0
@@ -115,9 +150,17 @@ def scan_img():
         ey += 1
 
     #print (sx,ex,sy,ey)
-    return(sx,sy,ex,ey)
+    return(sx,sy,ex,ey,total)
 
 def save_image():
+    """
+    For the size of the area we have reduced down to where the majority of dark pixels,
+    are located, store all that into a list and return the list.
+    
+    given start x, y and end x, y.
+    returns multiple strings in a list that are edited to use characters to represent,
+    the dark and light pixels of the image.
+    """
     result = []
     for y in range(sy,ey):
         s = ''
@@ -132,6 +175,15 @@ def save_image():
 
 def run(difficult):
     global size, pix, im
+    """
+    run, represents a single execution of components to the image, (Actuall we do it 1 category at a time instead of just 1 single execution )
+    those components do the following...                           (Each category has around 70 items so we standardize on 70, but           )
+                                                                   (not all of the categories have 70 and thus we print a File does not exist)
+    We open and load the image, and get it's size,
+    then we scan_img for dark and light pixels, <-- This narrows the image down to just the majority of dark pixels
+    then from that we output the image line by line onto the screen after it has been save_image d into list form,
+    Where we ask the user what the word is, and after that we save all that to a file in the data directory.
+    """
     
     for x in range(0, 70):
         fname = f'in/{difficult}_{x}.png'
@@ -175,6 +227,7 @@ def run(difficult):
         # os.remove(f'{fname}')  # Grr No bad bean, keep file for error checking
         # print(f"File '{fname}' automatically removed")
 
+# Now to call all the previous functions
 if (DOWNLOAD == True):
     print("Downloading s0urce.io Words")
     print("EASY")
@@ -202,6 +255,7 @@ if (DOWNLOAD == True):
 
 # ----------------------------------------------------------------------------------------
 # All below was in a seperate dataJS.py file... but now I have fixed it so it's 1 script!
+# Do we really need to worry about all this right now? (I think we have enough bugs to begin with.)
 
 if (JSONME.lower() != 'false'):
     print("Now exporting to JSON")
@@ -210,6 +264,9 @@ if (JSONME.lower() != 'false'):
 
     def test(t):
         global DIR
+        """
+        given the filename, we read it and add it to a list and return the list.
+        """
         fname = f'{DIR}/{t}.txt'
         r = []
         try:
@@ -222,6 +279,13 @@ if (JSONME.lower() != 'false'):
 
     def insertJS(item):
         global JSON
+        """
+        Edits the file given and adds the JSONIFIED item to the file between 2 indicators,
+        // T
+        and
+        // t
+        In between the T and t will be replaced with the item.
+        """
         item = json.dumps(item)
         item = f'{item},'
         r = []
@@ -257,4 +321,5 @@ if (JSONME.lower() != 'false'):
             word = te
             insertJS(word)
 
-print("Complete")
+# Regardless what we did let the user know we at least ran and we are now done
+print("Complete")