Convert an image to ascii art text.

    Suppose we have an image like that:

    .. image:: images/rabbit.png
        :align: left

    Put some codes::

        >>> from weatherlab.math.img2waveform import img2ascii
        >>> img2ascii(r"testdata\img2waveform\rabbit.png", 
        ...           r"testdata\img2waveform\asciiart.txt", pad=0)

    Then you will see this in asciiart.txt::


                               ******                                                   
                              ***  ***                         ****                     
                             **      **                     *********                   
                            **        **                   ***     ***                  
                           **          *                  **         **                 
                           **          **                **          **                 
                          **            *               ***           *                 
                          *             **              **            **                
                         **              *             **             **                
                         **              *             **              *                
                         *               **           **               *                
                        **               **           *                **               
                        **                *          **                **               
                        *                 *          **                **               
                        *                 **         *                 **               
                       **                 **        **                 **               
                       **                  *        **                 **               
                       **                  *        *                  **               
                       **                  *       **                   *               
                       **                  *       **                   *               
                       *                   **      **                   *               
                       *                   **      *                    *               
                       *                   **     **                    *               
                       *                   **     **                    *               
                       **                  **     **                   **               
                       **                   *     **                   **               
                       **                   *     *                    **               
                       **                   *     *                    **               
                       **                   *     *                    **               
                        *                   *    **                    **               
                        *                   *    **                    *                
                        **                  *    **                    *                
                        **                  *    **                    *                
                        **                  **   **                   **                
                         *                  **   **                   **                
                         *                  **   **                   **                
                         **                 **   **                   *                 
                         **                 **   **                  **                 
                          *                 **   **                  **                 
                          **                **   **                  *                  
                          **                *******                  *                  
                          **                *******                 **                  
                           **                                       **                  
                           **                                       *                   
                           **                                      **                   
                          ***                                      *                    
                        ****                                       ***                  
                      ***                                           ***                 
                     **                                              ****               
                    **                                                 ***              
                   **                                                   ***             
                  **                                                      **            
                 **                                                        **           
                 *                                                          **          
                **                                                           **         
               **                                                            **         
               **                                                             **        
              **                                                               **       
              **                                                               **       
             **                                                                 **      
             **                                                                 **      
             *                                                                   **     
             *                                                                   **     
            **                                                                    *     
            **                                                                    **    
            *                                                                     **    
            *                                                                     **    
           **                                                                      *    
           **                                                                      *    
           **                                                                      **   
           **                                                                      **   
           **                                                                      **   
           **                                                                      **   
           **            **                                                        **   
           **            ***                                      ***              **   
            *           ****                                      ****             **   
            *            ***                                      ****             **   
            **           **                                        **              *    
            **                                                                     *    
            **                                                                     *    
             *                                                                    **    
             **                                                                   **    
             **                                                                   *     
              *                                                                  **     
              **                                                                 **     
               **                                                               **      
               **                                                               *       
                **                                                             **       
                **                                                            **        
                 **                                                          **         
                  **                        ***  **                         **          
                   **                        ******                        ***          
                    ***                     ******                        **            
                     ***                     *  ***                     ***             
                       ***                                             ***              
                        ***                                          ***                
                          ****                                     ****                 
                         ********                                *******                
                        *** **********                       ******** ***               
                       **   ***  ************         ********** *** * ***              
                      **  * ****      ***********************   ***  ** ***             
                     ** *  ** ****  **       ******* *         *** ***** ***            
                    ****  *  * *****       **********      * **** *  * ** **            
                   ***  * * ** * ******************************* * ***   * **           
                   ** ***** * *** ********** **  ** **********   ***   **  ***          
                  ** * ***** **  *    *****  **  **   *****   * *  ** *     **          
                 ***  *** ************    ** ****** ** *    * ** ** ** * ** ***         
                 ** ******* *  * **    **  ** ****    *  ** *  **   * ****   **         
                ** *** *** ******* ****** * **   * *** ***** *** ** ***** **  **        
                ** * *  ***** ************************************ * ****  *  **        
               *** ** ** ***********************************************  *** ***       
                ***   ** ****************************************** **** ** ** **       
                ****  ** ** ******************************************** ** *  **       
               ** ****** ** ******************************************** ** *  ***      
               **  ***** *********************************************** **  ****       
               *     *** ****************************** **************** *********      
              **      **  *************************************** * * *  *****   *      
              **      ** **********************************************  ***     *      
               *      ** **  *********************************** ******* **      *      
               **     **  *****************************************  *** **      *      
                ***  ** * ********************************************** **     **      
                 ****** ************************************************ **   ***       
                   **** *********************************************** ********        
                     **  *********************************************** ****           
                     *** **  ******************************************* **             
                      *** ** ***** ****** * * * * *  ******** *** ** ** ***             
                       ***  *   * ****   ****  **** * ** **  * *** **  ***              
                        ****   * * ** **** * *** ********  *  ***   *****               
                         *****    ** **  ** **  ***  ** ***       *****                 
                           *******        * * ** * **        ********                   
                              *************** *   *******************                   
                               ******************************      ***                  
                              ***          *********                **                  
                              **                  *                  **                 
                             **                   *                  **                 
                             **                   *                  **                 
                             **                   *                  **                 
                             **                   *                  **                 
                             **                  **                 **                  
                              **                ****** *  ** *********                  
                               *************************************                    
                                  **********    

    :param img_path: the image file path
    :type img_path: str
    :param ascii_path: the output ascii text file path
    :type ascii_path: str
    :param pad: how many space been filled in between two pixels
    :type pad: int

def img2ascii(img_path, ascii_path, ascii_char="*", pad=0):
    """Convert an image to ascii art text.

    Suppose we have an image like that:

    .. image:: images/rabbit.png
        :align: left

    Put some codes::

        >>> from weatherlab.math.img2waveform import img2ascii
        >>> img2ascii(r"testdata\img2waveform\rabbit.png", 
        ...           r"testdata\img2waveform\asciiart.txt", pad=0)

    Then you will see this in asciiart.txt::


                               ******                                                   
                              ***  ***                         ****                     
                             **      **                     *********                   
                            **        **                   ***     ***                  
                           **          *                  **         **                 
                           **          **                **          **                 
                          **            *               ***           *                 
                          *             **              **            **                
                         **              *             **             **                
                         **              *             **              *                
                         *               **           **               *                
                        **               **           *                **               
                        **                *          **                **               
                        *                 *          **                **               
                        *                 **         *                 **               
                       **                 **        **                 **               
                       **                  *        **                 **               
                       **                  *        *                  **               
                       **                  *       **                   *               
                       **                  *       **                   *               
                       *                   **      **                   *               
                       *                   **      *                    *               
                       *                   **     **                    *               
                       *                   **     **                    *               
                       **                  **     **                   **               
                       **                   *     **                   **               
                       **                   *     *                    **               
                       **                   *     *                    **               
                       **                   *     *                    **               
                        *                   *    **                    **               
                        *                   *    **                    *                
                        **                  *    **                    *                
                        **                  *    **                    *                
                        **                  **   **                   **                
                         *                  **   **                   **                
                         *                  **   **                   **                
                         **                 **   **                   *                 
                         **                 **   **                  **                 
                          *                 **   **                  **                 
                          **                **   **                  *                  
                          **                *******                  *                  
                          **                *******                 **                  
                           **                                       **                  
                           **                                       *                   
                           **                                      **                   
                          ***                                      *                    
                        ****                                       ***                  
                      ***                                           ***                 
                     **                                              ****               
                    **                                                 ***              
                   **                                                   ***             
                  **                                                      **            
                 **                                                        **           
                 *                                                          **          
                **                                                           **         
               **                                                            **         
               **                                                             **        
              **                                                               **       
              **                                                               **       
             **                                                                 **      
             **                                                                 **      
             *                                                                   **     
             *                                                                   **     
            **                                                                    *     
            **                                                                    **    
            *                                                                     **    
            *                                                                     **    
           **                                                                      *    
           **                                                                      *    
           **                                                                      **   
           **                                                                      **   
           **                                                                      **   
           **                                                                      **   
           **            **                                                        **   
           **            ***                                      ***              **   
            *           ****                                      ****             **   
            *            ***                                      ****             **   
            **           **                                        **              *    
            **                                                                     *    
            **                                                                     *    
             *                                                                    **    
             **                                                                   **    
             **                                                                   *     
              *                                                                  **     
              **                                                                 **     
               **                                                               **      
               **                                                               *       
                **                                                             **       
                **                                                            **        
                 **                                                          **         
                  **                        ***  **                         **          
                   **                        ******                        ***          
                    ***                     ******                        **            
                     ***                     *  ***                     ***             
                       ***                                             ***              
                        ***                                          ***                
                          ****                                     ****                 
                         ********                                *******                
                        *** **********                       ******** ***               
                       **   ***  ************         ********** *** * ***              
                      **  * ****      ***********************   ***  ** ***             
                     ** *  ** ****  **       ******* *         *** ***** ***            
                    ****  *  * *****       **********      * **** *  * ** **            
                   ***  * * ** * ******************************* * ***   * **           
                   ** ***** * *** ********** **  ** **********   ***   **  ***          
                  ** * ***** **  *    *****  **  **   *****   * *  ** *     **          
                 ***  *** ************    ** ****** ** *    * ** ** ** * ** ***         
                 ** ******* *  * **    **  ** ****    *  ** *  **   * ****   **         
                ** *** *** ******* ****** * **   * *** ***** *** ** ***** **  **        
                ** * *  ***** ************************************ * ****  *  **        
               *** ** ** ***********************************************  *** ***       
                ***   ** ****************************************** **** ** ** **       
                ****  ** ** ******************************************** ** *  **       
               ** ****** ** ******************************************** ** *  ***      
               **  ***** *********************************************** **  ****       
               *     *** ****************************** **************** *********      
              **      **  *************************************** * * *  *****   *      
              **      ** **********************************************  ***     *      
               *      ** **  *********************************** ******* **      *      
               **     **  *****************************************  *** **      *      
                ***  ** * ********************************************** **     **      
                 ****** ************************************************ **   ***       
                   **** *********************************************** ********        
                     **  *********************************************** ****           
                     *** **  ******************************************* **             
                      *** ** ***** ****** * * * * *  ******** *** ** ** ***             
                       ***  *   * ****   ****  **** * ** **  * *** **  ***              
                        ****   * * ** **** * *** ********  *  ***   *****               
                         *****    ** **  ** **  ***  ** ***       *****                 
                           *******        * * ** * **        ********                   
                              *************** *   *******************                   
                               ******************************      ***                  
                              ***          *********                **                  
                              **                  *                  **                 
                             **                   *                  **                 
                             **                   *                  **                 
                             **                   *                  **                 
                             **                   *                  **                 
                             **                  **                 **                  
                              **                ****** *  ** *********                  
                               *************************************                    
                                  **********    

    :param img_path: the image file path
    :type img_path: str
    :param ascii_path: the output ascii text file path
    :type ascii_path: str
    :param pad: how many space been filled in between two pixels
    :type pad: int
    """
    if len(ascii_char) != 1:
        raise Exception("ascii_char has to be single character.")

    image = Image.open(img_path).convert("L")
    matrix = np.array(image)

    # you can customize the gray scale fix behavior to fit color image
    matrix[np.where(matrix >= 128)] = 255
    matrix[np.where(matrix < 128)] = 0

    lines = list()
    for vector in matrix:
        line = list()
        for i in vector:
            line.append(" " * pad)
            if i:
                line.append(" ")
            else:
                line.append(ascii_char)
        lines.append("".join(line))

    with open(ascii_path, "w") as f:
        f.write("\n".join(lines))