signature:
def load_imdb_dataset ( path = 'data' , nb_words = None , skip_top = 0 , maxlen = None , test_split = 0.2 , seed = 113 , start_char = 1 , oov_char = 2 , index_from = 3 ) :
    """Load IMDB dataset .
 Parameters
 path : str
 The path that the data is downloaded to , defaults is ` ` data / imdb / ` ` .
 nb _ words : int
 Number of words to get .
 skip _ top : int
 Top most frequent words to ignore ( they will appear as oov _ char value in the sequence data ) .
 maxlen : int
 Maximum sequence length . Any longer sequence will be truncated .
 seed : int
 Seed for reproducible data shuffling .
 start _ char : int
 The start of a sequence will be marked with this character . Set to 1 because 0 is usually the padding character .
 oov _ char : int
 Words that were cut out because of the num _ words or skip _ top limit will be replaced with this character .
 index _ from : int
 Index actual words with this index and higher .
 Examples
 > > > X _ train , y _ train , X _ test , y _ test = tl . files . load _ imdb _ dataset (
 . . . nb _ words = 20000 , test _ split = 0.2)
 > > > print ( ' X _ train . shape ' , X _ train . shape )
 (20000 , ) [ [ 1 , 62 , 74 , . . . 1033 , 507 , 27 ] , [ 1 , 60 , 33 , . . . 13 , 1053 , 7 ] . . ]
 > > > print ( ' y _ train . shape ' , y _ train . shape )
 (20000 , ) [ 1 0 0 . . . , 1 0 1]
 References
 - ` Modified from keras . < https : / / github . com / fchollet / keras / blob / master / keras / datasets / imdb . py > ` _ _"""

implementation:
path = os . path . join ( path , 'imdb' )
filename = "imdb.pkl"
url = 'https://s3.amazonaws.com/text-datasets/'
maybe_download_and_extract ( filename , path , url )
if filename . endswith ( ".gz" ) :
    f = gzip . open ( os . path . join ( path , filename ) , 'rb' )
else :
    f = open ( os . path . join ( path , filename ) , 'rb' )
X , labels = cPickle . load ( f )
f . close ( )
np . random . seed ( seed )
np . random . shuffle ( X )
np . random . seed ( seed )
np . random . shuffle ( labels )
if start_char is not None :
    X = [ [ start_char ] + [ w + index_from for w in x ] for x in X ]
elif index_from :
    X = [ [ w + index_from for w in x ] for x in X ]
if maxlen :
    new_X = [ ]
    new_labels = [ ]
    for x , y in zip ( X , labels ) :
        if len ( x ) < maxlen :
            new_X . append ( x )
            new_labels . append ( y )
    X = new_X
    labels = new_labels
if not X :
    raise Exception ( 'After filtering for sequences shorter than maxlen=' + str ( maxlen ) + ', no sequence was kept. ' 'Increase maxlen.' )
if not nb_words :
    nb_words = max ( [ max ( x ) for x in X ] )
# by convention , use 2 as OOV word
# reserve ' index _ from ' ( = 3 by default ) characters : 0 ( padding ) , 1 ( start ) , 2 ( OOV )
if oov_char is not None :
    X = [ [ oov_char if ( w >= nb_words or w < skip_top ) else w for w in x ] for x in X ]
else :
    nX = [ ]
    for x in X :
        nx = [ ]
        for w in x :
            if ( w >= nb_words or w < skip_top ) :
                nx . append ( w )
        nX . append ( nx )
    X = nX
X_train = np . array ( X [ : int ( len ( X ) * ( 1 - test_split ) ) ] )
y_train = np . array ( labels [ : int ( len ( X ) * ( 1 - test_split ) ) ] )
X_test = np . array ( X [ int ( len ( X ) * ( 1 - test_split ) ) : ] )
y_test = np . array ( labels [ int ( len ( X ) * ( 1 - test_split ) ) : ] )
return X_train , y_train , X_test , y_test


signature:
def load_nietzsche_dataset ( path = 'data' ) :
    """Load Nietzsche dataset .
 Parameters
 path : str
 The path that the data is downloaded to , defaults is ` ` data / nietzsche / ` ` .
 Returns
 str
 The content .
 Examples
 > > > see tutorial _ generate _ text . py
 > > > words = tl . files . load _ nietzsche _ dataset ( )
 > > > words = basic _ clean _ str ( words )
 > > > words = words . split ( )"""

implementation:
logging . info ( "Load or Download nietzsche dataset > {}" . format ( path ) )
path = os . path . join ( path , 'nietzsche' )
filename = "nietzsche.txt"
url = 'https://s3.amazonaws.com/text-datasets/'
filepath = maybe_download_and_extract ( filename , path , url )
with open ( filepath , "r" ) as f :
    words = f . read ( )
    return words


signature:
def load_flickr25k_dataset ( tag = 'sky' , path = "data" , n_threads = 50 , printable = False ) :
    """Load Flickr25K dataset .
 Returns a list of images by a given tag from Flick25k dataset ,
 it will download Flickr25k from ` the official website < http : / / press . liacs . nl / mirflickr / mirdownload . html > ` _ _
 at the first time you use it .
 Parameters
 tag : str or None
 What images to return .
 - If you want to get images with tag , use string like ' dog ' , ' red ' , see ` Flickr Search < https : / / www . flickr . com / search / > ` _ _ .
 - If you want to get all images , set to ` ` None ` ` .
 path : str
 The path that the data is downloaded to , defaults is ` ` data / flickr25k / ` ` .
 n _ threads : int
 The number of thread to read image .
 printable : boolean
 Whether to print infomation when reading images , default is ` ` False ` ` .
 Examples
 Get images with tag of sky
 > > > images = tl . files . load _ flickr25k _ dataset ( tag = ' sky ' )
 Get all images
 > > > images = tl . files . load _ flickr25k _ dataset ( tag = None , n _ threads = 100 , printable = True )"""

implementation:
path = os . path . join ( path , 'flickr25k' )
filename = 'mirflickr25k.zip'
url = 'http://press.liacs.nl/mirflickr/mirflickr25k/'
# download dataset
if folder_exists ( os . path . join ( path , "mirflickr" ) ) is False :
    logging . info ( "[*] Flickr25k is nonexistent in {}" . format ( path ) )
    maybe_download_and_extract ( filename , path , url , extract = True )
    del_file ( os . path . join ( path , filename ) )
# return images by the given tag .
# 1 . image path list
folder_imgs = os . path . join ( path , "mirflickr" )
path_imgs = load_file_list ( path = folder_imgs , regx = '\\.jpg' , printable = False )
path_imgs . sort ( key = natural_keys )
# 2 . tag path list
folder_tags = os . path . join ( path , "mirflickr" , "meta" , "tags" )
path_tags = load_file_list ( path = folder_tags , regx = '\\.txt' , printable = False )
path_tags . sort ( key = natural_keys )
# 3 . select images
if tag is None :
    logging . info ( "[Flickr25k] reading all images" )
else :
    logging . info ( "[Flickr25k] reading images with tag: {}" . format ( tag ) )
images_list = [ ]
for idx , _v in enumerate ( path_tags ) :
    tags = read_file ( os . path . join ( folder_tags , path_tags [ idx ] ) ) . split ( '\n' )
    # logging . info ( idx + 1 , tags )
    if tag is None or tag in tags :
        images_list . append ( path_imgs [ idx ] )
images = visualize . read_images ( images_list , folder_imgs , n_threads = n_threads , printable = printable )
return images


signature:
def load_flickr1M_dataset ( tag = 'sky' , size = 10 , path = "data" , n_threads = 50 , printable = False ) :
    """Load Flick1M dataset .
 Returns a list of images by a given tag from Flickr1M dataset ,
 it will download Flickr1M from ` the official website < http : / / press . liacs . nl / mirflickr / mirdownload . html > ` _ _
 at the first time you use it .
 Parameters
 tag : str or None
 What images to return .
 - If you want to get images with tag , use string like ' dog ' , ' red ' , see ` Flickr Search < https : / / www . flickr . com / search / > ` _ _ .
 - If you want to get all images , set to ` ` None ` ` .
 size : int
 integer between 1 to 10 . 1 means 100k images . . . 5 means 500k images , 10 means all 1 million images . Default is 10.
 path : str
 The path that the data is downloaded to , defaults is ` ` data / flickr25k / ` ` .
 n _ threads : int
 The number of thread to read image .
 printable : boolean
 Whether to print infomation when reading images , default is ` ` False ` ` .
 Examples
 Use 200k images
 > > > images = tl . files . load _ flickr1M _ dataset ( tag = ' zebra ' , size = 2)
 Use 1 Million images
 > > > images = tl . files . load _ flickr1M _ dataset ( tag = ' zebra ' )"""

implementation:
path = os . path . join ( path , 'flickr1M' )
logging . info ( "[Flickr1M] using {}% of images = {}" . format ( size * 10 , size * 100000 ) )
images_zip = [ 'images0.zip' , 'images1.zip' , 'images2.zip' , 'images3.zip' , 'images4.zip' , 'images5.zip' , 'images6.zip' , 'images7.zip' , 'images8.zip' , 'images9.zip' ]
tag_zip = 'tags.zip'
url = 'http://press.liacs.nl/mirflickr/mirflickr1m/'
# download dataset
for image_zip in images_zip [ 0 : size ] :
    image_folder = image_zip . split ( "." ) [ 0 ]
    # logging . info ( path + " / " + image _ folder )
    if folder_exists ( os . path . join ( path , image_folder ) ) is False : # logging . info ( image _ zip )
        logging . info ( "[Flickr1M] {} is missing in {}" . format ( image_folder , path ) )
        maybe_download_and_extract ( image_zip , path , url , extract = True )
        del_file ( os . path . join ( path , image_zip ) )
        # os . system ( " mv { } { } " . format ( os . path . join ( path , ' images ' ) , os . path . join ( path , image _ folder ) ) )
        shutil . move ( os . path . join ( path , 'images' ) , os . path . join ( path , image_folder ) )
    else :
        logging . info ( "[Flickr1M] {} exists in {}" . format ( image_folder , path ) )
# download tag
if folder_exists ( os . path . join ( path , "tags" ) ) is False :
    logging . info ( "[Flickr1M] tag files is nonexistent in {}" . format ( path ) )
    maybe_download_and_extract ( tag_zip , path , url , extract = True )
    del_file ( os . path . join ( path , tag_zip ) )
else :
    logging . info ( "[Flickr1M] tags exists in {}" . format ( path ) )
# 1 . image path list
images_list = [ ]
images_folder_list = [ ]
for i in range ( 0 , size ) :
    images_folder_list += load_folder_list ( path = os . path . join ( path , 'images%d' % i ) )
images_folder_list . sort ( key = lambda s : int ( s . split ( '/' ) [ - 1 ] ) )
# folder / images / ddd
for folder in images_folder_list [ 0 : size * 10 ] :
    tmp = load_file_list ( path = folder , regx = '\\.jpg' , printable = False )
    tmp . sort ( key = lambda s : int ( s . split ( '.' ) [ - 2 ] ) )
    # ddd . jpg
    images_list . extend ( [ os . path . join ( folder , x ) for x in tmp ] )
# 2 . tag path list
tag_list = [ ]
tag_folder_list = load_folder_list ( os . path . join ( path , "tags" ) )
# tag _ folder _ list . sort ( key = lambda s : int ( s . split ( " / " ) [ - 1 ] ) ) # folder / images / ddd
tag_folder_list . sort ( key = lambda s : int ( os . path . basename ( s ) ) )
for folder in tag_folder_list [ 0 : size * 10 ] :
    tmp = load_file_list ( path = folder , regx = '\\.txt' , printable = False )
    tmp . sort ( key = lambda s : int ( s . split ( '.' ) [ - 2 ] ) )
    # ddd . txt
    tmp = [ os . path . join ( folder , s ) for s in tmp ]
    tag_list += tmp
# 3 . select images
logging . info ( "[Flickr1M] searching tag: {}" . format ( tag ) )
select_images_list = [ ]
for idx , _val in enumerate ( tag_list ) :
    tags = read_file ( tag_list [ idx ] ) . split ( '\n' )
    if tag in tags :
        select_images_list . append ( images_list [ idx ] )
logging . info ( "[Flickr1M] reading images with tag: {}" . format ( tag ) )
images = visualize . read_images ( select_images_list , '' , n_threads = n_threads , printable = printable )
return images


signature:
def load_cyclegan_dataset ( filename = 'summer2winter_yosemite' , path = 'data' ) :
    """Load images from CycleGAN ' s database , see ` this link < https : / / people . eecs . berkeley . edu / ~ taesung _ park / CycleGAN / datasets / > ` _ _ .
 Parameters
 filename : str
 The dataset you want , see ` this link < https : / / people . eecs . berkeley . edu / ~ taesung _ park / CycleGAN / datasets / > ` _ _ .
 path : str
 The path that the data is downloaded to , defaults is ` data / cyclegan `
 Examples
 > > > im _ train _ A , im _ train _ B , im _ test _ A , im _ test _ B = load _ cyclegan _ dataset ( filename = ' summer2winter _ yosemite ' )"""

implementation:
path = os . path . join ( path , 'cyclegan' )
url = 'https://people.eecs.berkeley.edu/~taesung_park/CycleGAN/datasets/'
if folder_exists ( os . path . join ( path , filename ) ) is False :
    logging . info ( "[*] {} is nonexistent in {}" . format ( filename , path ) )
    maybe_download_and_extract ( filename + '.zip' , path , url , extract = True )
    del_file ( os . path . join ( path , filename + '.zip' ) )
def load_image_from_folder ( path ) :
    path_imgs = load_file_list ( path = path , regx = '\\.jpg' , printable = False )
    return visualize . read_images ( path_imgs , path = path , n_threads = 10 , printable = False )
im_train_A = load_image_from_folder ( os . path . join ( path , filename , "trainA" ) )
im_train_B = load_image_from_folder ( os . path . join ( path , filename , "trainB" ) )
im_test_A = load_image_from_folder ( os . path . join ( path , filename , "testA" ) )
im_test_B = load_image_from_folder ( os . path . join ( path , filename , "testB" ) )
def if_2d_to_3d ( images ) : # [ h , w ] - - > [ h , w , 3]
    for i , _v in enumerate ( images ) :
        if len ( images [ i ] . shape ) == 2 :
            images [ i ] = images [ i ] [ : , : , np . newaxis ]
            images [ i ] = np . tile ( images [ i ] , ( 1 , 1 , 3 ) )
    return images
im_train_A = if_2d_to_3d ( im_train_A )
im_train_B = if_2d_to_3d ( im_train_B )
im_test_A = if_2d_to_3d ( im_test_A )
im_test_B = if_2d_to_3d ( im_test_B )
return im_train_A , im_train_B , im_test_A , im_test_B


signature:
def download_file_from_google_drive ( ID , destination ) :
    """Download file from Google Drive .
 See ` ` tl . files . load _ celebA _ dataset ` ` for example .
 Parameters
 ID : str
 The driver ID .
 destination : str
 The destination for save file ."""

implementation:
def save_response_content ( response , destination , chunk_size = 32 * 1024 ) :
    total_size = int ( response . headers . get ( 'content-length' , 0 ) )
    with open ( destination , "wb" ) as f :
        for chunk in tqdm ( response . iter_content ( chunk_size ) , total = total_size , unit = 'B' , unit_scale = True , desc = destination ) :
            if chunk : # filter out keep - alive new chunks
                f . write ( chunk )
def get_confirm_token ( response ) :
    for key , value in response . cookies . items ( ) :
        if key . startswith ( 'download_warning' ) :
            return value
    return None
URL = "https://docs.google.com/uc?export=download"
session = requests . Session ( )
response = session . get ( URL , params = { 'id' : ID } , stream = True )
token = get_confirm_token ( response )
if token :
    params = { 'id' : ID , 'confirm' : token }
    response = session . get ( URL , params = params , stream = True )
save_response_content ( response , destination )


signature:
def load_celebA_dataset ( path = 'data' ) :
    """Load CelebA dataset
 Return a list of image path .
 Parameters
 path : str
 The path that the data is downloaded to , defaults is ` ` data / celebA / ` ` ."""

implementation:
data_dir = 'celebA'
filename , drive_id = "img_align_celeba.zip" , "0B7EVK8r0v71pZjFTYXZWM3FlRnM"
save_path = os . path . join ( path , filename )
image_path = os . path . join ( path , data_dir )
if os . path . exists ( image_path ) :
    logging . info ( '[*] {} already exists' . format ( save_path ) )
else :
    exists_or_mkdir ( path )
    download_file_from_google_drive ( drive_id , save_path )
    zip_dir = ''
    with zipfile . ZipFile ( save_path ) as zf :
        zip_dir = zf . namelist ( ) [ 0 ]
        zf . extractall ( path )
    os . remove ( save_path )
    os . rename ( os . path . join ( path , zip_dir ) , image_path )
data_files = load_file_list ( path = image_path , regx = '\\.jpg' , printable = False )
for i , _v in enumerate ( data_files ) :
    data_files [ i ] = os . path . join ( image_path , data_files [ i ] )
return data_files


signature:
def save_npz ( save_list = None , name = 'model.npz' , sess = None ) :
    """Input parameters and the file name , save parameters into . npz file . Use tl . utils . load _ npz ( ) to restore .
 Parameters
 save _ list : list of tensor
 A list of parameters ( tensor ) to be saved .
 name : str
 The name of the ` . npz ` file .
 sess : None or Session
 Session may be required in some case .
 Examples
 Save model to npz
 > > > tl . files . save _ npz ( network . all _ params , name = ' model . npz ' , sess = sess )
 Load model from npz ( Method 1)
 > > > load _ params = tl . files . load _ npz ( name = ' model . npz ' )
 > > > tl . files . assign _ params ( sess , load _ params , network )
 Load model from npz ( Method 2)
 > > > tl . files . load _ and _ assign _ npz ( sess = sess , name = ' model . npz ' , network = network )
 Notes
 If you got session issues , you can change the value . eval ( ) to value . eval ( session = sess )
 References
 ` Saving dictionary using numpy < http : / / stackoverflow . com / questions / 22315595 / saving - dictionary - of - header - information - using - numpy - savez > ` _ _"""

implementation:
logging . info ( "[*] Saving TL params into %s" % name )
if save_list is None :
    save_list = [ ]
save_list_var = [ ]
if sess :
    save_list_var = sess . run ( save_list )
else :
    try :
        save_list_var . extend ( [ v . eval ( ) for v in save_list ] )
    except Exception :
        logging . info ( " Fail to save model, Hint: pass the session into this function, tl.files.save_npz(network.all_params, name='model.npz', sess=sess)" )
np . savez ( name , params = save_list_var )
save_list_var = None
del save_list_var
logging . info ( "[*] Saved" )


signature:
def load_npz ( path = '' , name = 'model.npz' ) :
    """Load the parameters of a Model saved by tl . files . save _ npz ( ) .
 Parameters
 path : str
 Folder path to ` . npz ` file .
 name : str
 The name of the ` . npz ` file .
 Returns
 list of array
 A list of parameters in order .
 Examples
 - See ` ` tl . files . save _ npz ` `
 References
 - ` Saving dictionary using numpy < http : / / stackoverflow . com / questions / 22315595 / saving - dictionary - of - header - information - using - numpy - savez > ` _ _"""

implementation:
d = np . load ( os . path . join ( path , name ) )
return d [ 'params' ]


signature:
def assign_params ( sess , params , network ) :
    """Assign the given parameters to the TensorLayer network .
 Parameters
 sess : Session
 TensorFlow Session .
 params : list of array
 A list of parameters ( array ) in order .
 network : : class : ` Layer `
 The network to be assigned .
 Returns
 list of operations
 A list of tf ops in order that assign params . Support sess . run ( ops ) manually .
 Examples
 - See ` ` tl . files . save _ npz ` `
 References
 - ` Assign value to a TensorFlow variable < http : / / stackoverflow . com / questions / 34220532 / how - to - assign - value - to - a - tensorflow - variable > ` _ _"""

implementation:
ops = [ ]
for idx , param in enumerate ( params ) :
    ops . append ( network . all_params [ idx ] . assign ( param ) )
if sess is not None :
    sess . run ( ops )
return ops


signature:
def load_and_assign_npz ( sess = None , name = None , network = None ) :
    """Load model from npz and assign to a network .
 Parameters
 sess : Session
 TensorFlow Session .
 name : str
 The name of the ` . npz ` file .
 network : : class : ` Layer `
 The network to be assigned .
 Returns
 False or network
 Returns False , if the model is not exist .
 Examples
 - See ` ` tl . files . save _ npz ` `"""

implementation:
if network is None :
    raise ValueError ( "network is None." )
if sess is None :
    raise ValueError ( "session is None." )
if not os . path . exists ( name ) :
    logging . error ( "file {} doesn't exist." . format ( name ) )
    return False
else :
    params = load_npz ( name = name )
    assign_params ( sess , params , network )
    logging . info ( "[*] Load {} SUCCESS!" . format ( name ) )
    return network


signature:
def save_npz_dict ( save_list = None , name = 'model.npz' , sess = None ) :
    """Input parameters and the file name , save parameters as a dictionary into . npz file .
 Use ` ` tl . files . load _ and _ assign _ npz _ dict ( ) ` ` to restore .
 Parameters
 save _ list : list of parameters
 A list of parameters ( tensor ) to be saved .
 name : str
 The name of the ` . npz ` file .
 sess : Session
 TensorFlow Session ."""

implementation:
if sess is None :
    raise ValueError ( "session is None." )
if save_list is None :
    save_list = [ ]
save_list_names = [ tensor . name for tensor in save_list ]
save_list_var = sess . run ( save_list )
save_var_dict = { save_list_names [ idx ] : val for idx , val in enumerate ( save_list_var ) }
np . savez ( name , ** save_var_dict )
save_list_var = None
save_var_dict = None
del save_list_var
del save_var_dict
logging . info ( "[*] Model saved in npz_dict %s" % name )


signature:
def load_and_assign_npz_dict ( name = 'model.npz' , sess = None ) :
    """Restore the parameters saved by ` ` tl . files . save _ npz _ dict ( ) ` ` .
 Parameters
 name : str
 The name of the ` . npz ` file .
 sess : Session
 TensorFlow Session ."""

implementation:
if sess is None :
    raise ValueError ( "session is None." )
if not os . path . exists ( name ) :
    logging . error ( "file {} doesn't exist." . format ( name ) )
    return False
params = np . load ( name )
if len ( params . keys ( ) ) != len ( set ( params . keys ( ) ) ) :
    raise Exception ( "Duplication in model npz_dict %s" % name )
ops = list ( )
for key in params . keys ( ) :
    try : # tensor = tf . get _ default _ graph ( ) . get _ tensor _ by _ name ( key )
    # varlist = tf . get _ collection ( tf . GraphKeys . TRAINABLE _ VARIABLES , scope = key )
        varlist = tf . get_collection ( tf . GraphKeys . GLOBAL_VARIABLES , scope = key )
        if len ( varlist ) > 1 :
            raise Exception ( "[!] Multiple candidate variables to be assigned for name %s" % key )
        elif len ( varlist ) == 0 :
            raise KeyError
        else :
            ops . append ( varlist [ 0 ] . assign ( params [ key ] ) )
            logging . info ( "[*] params restored: %s" % key )
    except KeyError :
        logging . info ( "[!] Warning: Tensor named %s not found in network." % key )
sess . run ( ops )
logging . info ( "[*] Model restored from npz_dict %s" % name )


signature:
def save_ckpt ( sess = None , mode_name = 'model.ckpt' , save_dir = 'checkpoint' , var_list = None , global_step = None , printable = False ) :
    """Save parameters into ` ckpt ` file .
 Parameters
 sess : Session
 TensorFlow Session .
 mode _ name : str
 The name of the model , default is ` ` model . ckpt ` ` .
 save _ dir : str
 The path / file directory to the ` ckpt ` , default is ` ` checkpoint ` ` .
 var _ list : list of tensor
 The parameters / variables ( tensor ) to be saved . If empty , save all global variables ( default ) .
 global _ step : int or None
 Step number .
 printable : boolean
 Whether to print all parameters information .
 See Also
 load _ ckpt"""

implementation:
if sess is None :
    raise ValueError ( "session is None." )
if var_list is None :
    var_list = [ ]
ckpt_file = os . path . join ( save_dir , mode_name )
if var_list == [ ] :
    var_list = tf . global_variables ( )
logging . info ( "[*] save %s n_params: %d" % ( ckpt_file , len ( var_list ) ) )
if printable :
    for idx , v in enumerate ( var_list ) :
        logging . info ( "  param {:3}: {:15}   {}" . format ( idx , v . name , str ( v . get_shape ( ) ) ) )
saver = tf . train . Saver ( var_list )
saver . save ( sess , ckpt_file , global_step = global_step )


signature:
def load_ckpt ( sess = None , mode_name = 'model.ckpt' , save_dir = 'checkpoint' , var_list = None , is_latest = True , printable = False ) :
    """Load parameters from ` ckpt ` file .
 Parameters
 sess : Session
 TensorFlow Session .
 mode _ name : str
 The name of the model , default is ` ` model . ckpt ` ` .
 save _ dir : str
 The path / file directory to the ` ckpt ` , default is ` ` checkpoint ` ` .
 var _ list : list of tensor
 The parameters / variables ( tensor ) to be saved . If empty , save all global variables ( default ) .
 is _ latest : boolean
 Whether to load the latest ` ckpt ` , if False , load the ` ckpt ` with the name of ` ` ` mode _ name ` ` .
 printable : boolean
 Whether to print all parameters information .
 Examples
 - Save all global parameters .
 > > > tl . files . save _ ckpt ( sess = sess , mode _ name = ' model . ckpt ' , save _ dir = ' model ' , printable = True )
 - Save specific parameters .
 > > > tl . files . save _ ckpt ( sess = sess , mode _ name = ' model . ckpt ' , var _ list = net . all _ params , save _ dir = ' model ' , printable = True )
 - Load latest ckpt .
 > > > tl . files . load _ ckpt ( sess = sess , var _ list = net . all _ params , save _ dir = ' model ' , printable = True )
 - Load specific ckpt .
 > > > tl . files . load _ ckpt ( sess = sess , mode _ name = ' model . ckpt ' , var _ list = net . all _ params , save _ dir = ' model ' , is _ latest = False , printable = True )"""

implementation:
if sess is None :
    raise ValueError ( "session is None." )
if var_list is None :
    var_list = [ ]
if is_latest :
    ckpt_file = tf . train . latest_checkpoint ( save_dir )
else :
    ckpt_file = os . path . join ( save_dir , mode_name )
if not var_list :
    var_list = tf . global_variables ( )
logging . info ( "[*] load %s n_params: %d" % ( ckpt_file , len ( var_list ) ) )
if printable :
    for idx , v in enumerate ( var_list ) :
        logging . info ( "  param {:3}: {:15}   {}" . format ( idx , v . name , str ( v . get_shape ( ) ) ) )
try :
    saver = tf . train . Saver ( var_list )
    saver . restore ( sess , ckpt_file )
except Exception as e :
    logging . info ( e )
    logging . info ( "[*] load ckpt fail ..." )


signature:
def load_npy_to_any ( path = '' , name = 'file.npy' ) :
    """Load ` . npy ` file .
 Parameters
 path : str
 Path to the file ( optional ) .
 name : str
 File name .
 Examples
 - see tl . files . save _ any _ to _ npy ( )"""

implementation:
file_path = os . path . join ( path , name )
try :
    return np . load ( file_path ) . item ( )
except Exception :
    return np . load ( file_path )
raise Exception ( "[!] Fail to load %s" % file_path )


signature:
def load_file_list ( path = None , regx = '\.jpg' , printable = True , keep_prefix = False ) :
    r"""Return a file list in a folder by given a path and regular expression .
 Parameters
 path : str or None
 A folder path , if ` None ` , use the current directory .
 regx : str
 The regx of file name .
 printable : boolean
 Whether to print the files infomation .
 keep _ prefix : boolean
 Whether to keep path in the file name .
 Examples
 > > > file _ list = tl . files . load _ file _ list ( path = None , regx = ' w1pre _ [ 0-9 ] + \ . ( npz ) ' )"""

implementation:
if path is None :
    path = os . getcwd ( )
file_list = os . listdir ( path )
return_list = [ ]
for _ , f in enumerate ( file_list ) :
    if re . search ( regx , f ) :
        return_list . append ( f )
# return _ list . sort ( )
if keep_prefix :
    for i , f in enumerate ( return_list ) :
        return_list [ i ] = os . path . join ( path , f )
if printable :
    logging . info ( 'Match file list = %s' % return_list )
    logging . info ( 'Number of files = %d' % len ( return_list ) )
return return_list


signature:
def load_folder_list ( path = "" ) :
    """Return a folder list in a folder by given a folder path .
 Parameters
 path : str
 A folder path ."""

implementation: return [ os . path . join ( path , o ) for o in os . listdir ( path ) if os . path . isdir ( os . path . join ( path , o ) ) ]


signature:
def exists_or_mkdir ( path , verbose = True ) :
    """Check a folder by given name , if not exist , create the folder and return False ,
 if directory exists , return True .
 Parameters
 path : str
 A folder path .
 verbose : boolean
 If True ( default ) , prints results .
 Returns
 boolean
 True if folder already exist , otherwise , returns False and create the folder .
 Examples
 > > > tl . files . exists _ or _ mkdir ( " checkpoints / train " )"""

implementation:
if not os . path . exists ( path ) :
    if verbose :
        logging . info ( "[*] creates %s ..." % path )
    os . makedirs ( path )
    return False
else :
    if verbose :
        logging . info ( "[!] %s exists ..." % path )
    return True


signature:
def maybe_download_and_extract ( filename , working_directory , url_source , extract = False , expected_bytes = None ) :
    """Checks if file exists in working _ directory otherwise tries to dowload the file ,
 and optionally also tries to extract the file if format is " . zip " or " . tar "
 Parameters
 filename : str
 The name of the ( to be ) dowloaded file .
 working _ directory : str
 A folder path to search for the file in and dowload the file to
 url : str
 The URL to download the file from
 extract : boolean
 If True , tries to uncompress the dowloaded file is " . tar . gz / . tar . bz2 " or " . zip " file , default is False .
 expected _ bytes : int or None
 If set tries to verify that the downloaded file is of the specified size , otherwise raises an Exception , defaults is None which corresponds to no check being performed .
 Returns
 str
 File path of the dowloaded ( uncompressed ) file .
 Examples
 > > > down _ file = tl . files . maybe _ download _ and _ extract ( filename = ' train - images - idx3 - ubyte . gz ' ,
 . . . working _ directory = ' data / ' ,
 . . . url _ source = ' http : / / yann . lecun . com / exdb / mnist / ' )
 > > > tl . files . maybe _ download _ and _ extract ( filename = ' ADEChallengeData2016 . zip ' ,
 . . . working _ directory = ' data / ' ,
 . . . url _ source = ' http : / / sceneparsing . csail . mit . edu / data / ' ,
 . . . extract = True )"""

implementation:
# We first define a download function , supporting both Python 2 and 3.
def _download ( filename , working_directory , url_source ) :
    progress_bar = progressbar . ProgressBar ( )
    def _dlProgress ( count , blockSize , totalSize , pbar = progress_bar ) :
        if ( totalSize != 0 ) :
            if not pbar . max_value :
                totalBlocks = math . ceil ( float ( totalSize ) / float ( blockSize ) )
                pbar . max_value = int ( totalBlocks )
            pbar . update ( count , force = True )
    filepath = os . path . join ( working_directory , filename )
    logging . info ( 'Downloading %s...\n' % filename )
    urlretrieve ( url_source + filename , filepath , reporthook = _dlProgress )
exists_or_mkdir ( working_directory , verbose = False )
filepath = os . path . join ( working_directory , filename )
if not os . path . exists ( filepath ) :
    _download ( filename , working_directory , url_source )
    statinfo = os . stat ( filepath )
    logging . info ( 'Succesfully downloaded %s %s bytes.' % ( filename , statinfo . st_size ) )
    # , ' bytes . ' )
    if ( not ( expected_bytes is None ) and ( expected_bytes != statinfo . st_size ) ) :
        raise Exception ( 'Failed to verify ' + filename + '. Can you get to it with a browser?' )
    if ( extract ) :
        if tarfile . is_tarfile ( filepath ) :
            logging . info ( 'Trying to extract tar file' )
            tarfile . open ( filepath , 'r' ) . extractall ( working_directory )
            logging . info ( '... Success!' )
        elif zipfile . is_zipfile ( filepath ) :
            logging . info ( 'Trying to extract zip file' )
            with zipfile . ZipFile ( filepath ) as zf :
                zf . extractall ( working_directory )
            logging . info ( '... Success!' )
        else :
            logging . info ( "Unknown compression_format only .tar.gz/.tar.bz2/.tar and .zip supported" )
return filepath


signature:
def natural_keys ( text ) :
    """Sort list of string with number in human order .
 Examples
 > > > l = [ ' im1 . jpg ' , ' im31 . jpg ' , ' im11 . jpg ' , ' im21 . jpg ' , ' im03 . jpg ' , ' im05 . jpg ' ]
 > > > l . sort ( key = tl . files . natural _ keys )
 [ ' im1 . jpg ' , ' im03 . jpg ' , ' im05 ' , ' im11 . jpg ' , ' im21 . jpg ' , ' im31 . jpg ' ]
 > > > l . sort ( ) # that is what we dont want
 [ ' im03 . jpg ' , ' im05 ' , ' im1 . jpg ' , ' im11 . jpg ' , ' im21 . jpg ' , ' im31 . jpg ' ]
 References
 - ` link < http : / / nedbatchelder . com / blog / 200712 / human _ sorting . html > ` _ _"""

implementation:
# - alist . sort ( key = natural _ keys ) sorts in human order
# http : / / nedbatchelder . com / blog / 200712 / human _ sorting . html
# ( See Toothy ' s implementation in the comments )
def atoi ( text ) :
    return int ( text ) if text . isdigit ( ) else text
return [ atoi ( c ) for c in re . split ( '(\d+)' , text ) ]


signature:
def npz_to_W_pdf ( path = None , regx = 'w1pre_[0-9]+\.(npz)' ) :
    r"""Convert the first weight matrix of ` . npz ` file to ` . pdf ` by using ` tl . visualize . W ( ) ` .
 Parameters
 path : str
 A folder path to ` npz ` files .
 regx : str
 Regx for the file name .
 Examples
 Convert the first weight matrix of w1 _ pre . . . npz file to w1 _ pre . . . pdf .
 > > > tl . files . npz _ to _ W _ pdf ( path = ' / Users / . . . / npz _ file / ' , regx = ' w1pre _ [ 0-9 ] + \ . ( npz ) ' )"""

implementation:
file_list = load_file_list ( path = path , regx = regx )
for f in file_list :
    W = load_npz ( path , f ) [ 0 ]
    logging . info ( "%s --> %s" % ( f , f . split ( '.' ) [ 0 ] + '.pdf' ) )
    visualize . draw_weights ( W , second = 10 , saveable = True , name = f . split ( '.' ) [ 0 ] , fig_idx = 2012 )


signature:
def threading_data ( data = None , fn = None , thread_count = None , ** kwargs ) :
    """Process a batch of data by given function by threading .
 Usually be used for data augmentation .
 Parameters
 data : numpy . array or others
 The data to be processed .
 thread _ count : int
 The number of threads to use .
 fn : function
 The function for data processing .
 more args : the args for ` fn `
 Ssee Examples below .
 Examples
 Process images .
 > > > images , _ , _ , _ = tl . files . load _ cifar10 _ dataset ( shape = ( - 1 , 32 , 32 , 3 ) )
 > > > images = tl . prepro . threading _ data ( images [ 0:32 ] , tl . prepro . zoom , zoom _ range = [ 0.5 , 1 ] )
 Customized image preprocessing function .
 > > > def distort _ img ( x ) :
 > > > x = tl . prepro . flip _ axis ( x , axis = 0 , is _ random = True )
 > > > x = tl . prepro . flip _ axis ( x , axis = 1 , is _ random = True )
 > > > x = tl . prepro . crop ( x , 100 , 100 , is _ random = True )
 > > > return x
 > > > images = tl . prepro . threading _ data ( images , distort _ img )
 Process images and masks together ( Usually be used for image segmentation ) .
 > > > X , Y - - > [ batch _ size , row , col , 1]
 > > > data = tl . prepro . threading _ data ( [ _ for _ in zip ( X , Y ) ] , tl . prepro . zoom _ multi , zoom _ range = [ 0.5 , 1 ] , is _ random = True )
 data - - > [ batch _ size , 2 , row , col , 1]
 > > > X _ , Y _ = data . transpose ( ( 1,0,2,3,4 ) )
 X _ , Y _ - - > [ batch _ size , row , col , 1]
 > > > tl . vis . save _ image ( X _ , ' images . png ' )
 > > > tl . vis . save _ image ( Y _ , ' masks . png ' )
 Process images and masks together by using ` ` thread _ count ` ` .
 > > > X , Y - - > [ batch _ size , row , col , 1]
 > > > data = tl . prepro . threading _ data ( X , tl . prepro . zoom _ multi , 8 , zoom _ range = [ 0.5 , 1 ] , is _ random = True )
 data - - > [ batch _ size , 2 , row , col , 1]
 > > > X _ , Y _ = data . transpose ( ( 1,0,2,3,4 ) )
 X _ , Y _ - - > [ batch _ size , row , col , 1]
 > > > tl . vis . save _ image ( X _ , ' after . png ' )
 > > > tl . vis . save _ image ( Y _ , ' before . png ' )
 Customized function for processing images and masks together .
 > > > def distort _ img ( data ) :
 > > > x , y = data
 > > > x , y = tl . prepro . flip _ axis _ multi ( [ x , y ] , axis = 0 , is _ random = True )
 > > > x , y = tl . prepro . flip _ axis _ multi ( [ x , y ] , axis = 1 , is _ random = True )
 > > > x , y = tl . prepro . crop _ multi ( [ x , y ] , 100 , 100 , is _ random = True )
 > > > return x , y
 > > > X , Y - - > [ batch _ size , row , col , channel ]
 > > > data = tl . prepro . threading _ data ( [ _ for _ in zip ( X , Y ) ] , distort _ img )
 > > > X _ , Y _ = data . transpose ( ( 1,0,2,3,4 ) )
 Returns
 list or numpyarray
 The processed results .
 References
 - ` python queue < https : / / pymotw . com / 2 / Queue / index . html # module - Queue > ` _ _
 - ` run with limited queue < http : / / effbot . org / librarybook / queue . htm > ` _ _"""

implementation:
def apply_fn ( results , i , data , kwargs ) :
    results [ i ] = fn ( data , ** kwargs )
if thread_count is None :
    results = [ None ] * len ( data )
    threads = [ ]
    # for i in range ( len ( data ) ) :
    # t = threading . Thread ( name = ' threading _ and _ return ' , target = apply _ fn , args = ( results , i , data [ i ] , kwargs ) )
    for i , d in enumerate ( data ) :
        t = threading . Thread ( name = 'threading_and_return' , target = apply_fn , args = ( results , i , d , kwargs ) )
        t . start ( )
        threads . append ( t )
else :
    divs = np . linspace ( 0 , len ( data ) , thread_count + 1 )
    divs = np . round ( divs ) . astype ( int )
    results = [ None ] * thread_count
    threads = [ ]
    for i in range ( thread_count ) :
        t = threading . Thread ( name = 'threading_and_return' , target = apply_fn , args = ( results , i , data [ divs [ i ] : divs [ i + 1 ] ] , kwargs ) )
        t . start ( )
        threads . append ( t )
for t in threads :
    t . join ( )
if thread_count is None :
    try :
        return np . asarray ( results )
    except Exception :
        return results
else :
    return np . concatenate ( results )


signature:
def affine_rotation_matrix ( angle = ( - 20 , 20 ) ) :
    """Create an affine transform matrix for image rotation .
 NOTE : In OpenCV , x is width and y is height .
 Parameters
 angle : int / float or tuple of two int / float
 Degree to rotate , usually - 180 ~ 180.
 - int / float , a fixed angle .
 - tuple of 2 floats / ints , randomly sample a value as the angle between these 2 values .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
if isinstance ( angle , tuple ) :
    theta = np . pi / 180 * np . random . uniform ( angle [ 0 ] , angle [ 1 ] )
else :
    theta = np . pi / 180 * angle
rotation_matrix = np . array ( [ [ np . cos ( theta ) , np . sin ( theta ) , 0 ] , [ - np . sin ( theta ) , np . cos ( theta ) , 0 ] , [ 0 , 0 , 1 ] ] )
return rotation_matrix


signature:
def affine_horizontal_flip_matrix ( prob = 0.5 ) :
    """Create an affine transformation matrix for image horizontal flipping .
 NOTE : In OpenCV , x is width and y is height .
 Parameters
 prob : float
 Probability to flip the image . 1.0 means always flip .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
factor = np . random . uniform ( 0 , 1 )
if prob >= factor :
    filp_matrix = np . array ( [ [ - 1. , 0. , 0. ] , [ 0. , 1. , 0. ] , [ 0. , 0. , 1. ] ] )
    return filp_matrix
else :
    filp_matrix = np . array ( [ [ 1. , 0. , 0. ] , [ 0. , 1. , 0. ] , [ 0. , 0. , 1. ] ] )
    return filp_matrix


signature:
def affine_vertical_flip_matrix ( prob = 0.5 ) :
    """Create an affine transformation for image vertical flipping .
 NOTE : In OpenCV , x is width and y is height .
 Parameters
 prob : float
 Probability to flip the image . 1.0 means always flip .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
factor = np . random . uniform ( 0 , 1 )
if prob >= factor :
    filp_matrix = np . array ( [ [ 1. , 0. , 0. ] , [ 0. , - 1. , 0. ] , [ 0. , 0. , 1. ] ] )
    return filp_matrix
else :
    filp_matrix = np . array ( [ [ 1. , 0. , 0. ] , [ 0. , 1. , 0. ] , [ 0. , 0. , 1. ] ] )
    return filp_matrix


signature:
def affine_shift_matrix ( wrg = ( - 0.1 , 0.1 ) , hrg = ( - 0.1 , 0.1 ) , w = 200 , h = 200 ) :
    """Create an affine transform matrix for image shifting .
 NOTE : In OpenCV , x is width and y is height .
 Parameters
 wrg : float or tuple of floats
 Range to shift on width axis , - 1 ~ 1.
 - float , a fixed distance .
 - tuple of 2 floats , randomly sample a value as the distance between these 2 values .
 hrg : float or tuple of floats
 Range to shift on height axis , - 1 ~ 1.
 - float , a fixed distance .
 - tuple of 2 floats , randomly sample a value as the distance between these 2 values .
 w , h : int
 The width and height of the image .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
if isinstance ( wrg , tuple ) :
    tx = np . random . uniform ( wrg [ 0 ] , wrg [ 1 ] ) * w
else :
    tx = wrg * w
if isinstance ( hrg , tuple ) :
    ty = np . random . uniform ( hrg [ 0 ] , hrg [ 1 ] ) * h
else :
    ty = hrg * h
shift_matrix = np . array ( [ [ 1 , 0 , tx ] , [ 0 , 1 , ty ] , [ 0 , 0 , 1 ] ] )
return shift_matrix


signature:
def affine_shear_matrix ( x_shear = ( - 0.1 , 0.1 ) , y_shear = ( - 0.1 , 0.1 ) ) :
    """Create affine transform matrix for image shearing .
 NOTE : In OpenCV , x is width and y is height .
 Parameters
 shear : tuple of two floats
 Percentage of shears for width and height directions .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
# if len ( shear ) ! = 2:
# raise AssertionError (
# " shear should be tuple of 2 floats , or you want to use tl . prepro . shear rather than tl . prepro . shear2 ? "
# if isinstance ( shear , tuple ) :
# shear = list ( shear )
# if is _ random :
# shear [ 0 ] = np . random . uniform ( - shear [ 0 ] , shear [ 0 ] )
# shear [ 1 ] = np . random . uniform ( - shear [ 1 ] , shear [ 1 ] )
if isinstance ( x_shear , tuple ) :
    x_shear = np . random . uniform ( x_shear [ 0 ] , x_shear [ 1 ] )
if isinstance ( y_shear , tuple ) :
    y_shear = np . random . uniform ( y_shear [ 0 ] , y_shear [ 1 ] )
shear_matrix = np . array ( [ [ 1 , x_shear , 0 ] , [ y_shear , 1 , 0 ] , [ 0 , 0 , 1 ] ] )
return shear_matrix


signature:
def affine_zoom_matrix ( zoom_range = ( 0.8 , 1.1 ) ) :
    """Create an affine transform matrix for zooming / scaling an image ' s height and width .
 OpenCV format , x is width .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 zoom _ range : float or tuple of 2 floats
 The zooming / scaling ratio , greater than 1 means larger .
 - float , a fixed ratio .
 - tuple of 2 floats , randomly sample a value as the ratio between these 2 values .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
if isinstance ( zoom_range , ( float , int ) ) :
    scale = zoom_range
elif isinstance ( zoom_range , tuple ) :
    scale = np . random . uniform ( zoom_range [ 0 ] , zoom_range [ 1 ] )
else :
    raise Exception ( "zoom_range: float or tuple of 2 floats" )
zoom_matrix = np . array ( [ [ scale , 0 , 0 ] , [ 0 , scale , 0 ] , [ 0 , 0 , 1 ] ] )
return zoom_matrix


signature:
def affine_respective_zoom_matrix ( w_range = 0.8 , h_range = 1.1 ) :
    """Get affine transform matrix for zooming / scaling that height and width are changed independently .
 OpenCV format , x is width .
 Parameters
 w _ range : float or tuple of 2 floats
 The zooming / scaling ratio of width , greater than 1 means larger .
 - float , a fixed ratio .
 - tuple of 2 floats , randomly sample a value as the ratio between 2 values .
 h _ range : float or tuple of 2 floats
 The zooming / scaling ratio of height , greater than 1 means larger .
 - float , a fixed ratio .
 - tuple of 2 floats , randomly sample a value as the ratio between 2 values .
 Returns
 numpy . array
 An affine transform matrix ."""

implementation:
if isinstance ( h_range , ( float , int ) ) :
    zy = h_range
elif isinstance ( h_range , tuple ) :
    zy = np . random . uniform ( h_range [ 0 ] , h_range [ 1 ] )
else :
    raise Exception ( "h_range: float or tuple of 2 floats" )
if isinstance ( w_range , ( float , int ) ) :
    zx = w_range
elif isinstance ( w_range , tuple ) :
    zx = np . random . uniform ( w_range [ 0 ] , w_range [ 1 ] )
else :
    raise Exception ( "w_range: float or tuple of 2 floats" )
zoom_matrix = np . array ( [ [ zx , 0 , 0 ] , [ 0 , zy , 0 ] , [ 0 , 0 , 1 ] ] )
return zoom_matrix


signature:
def transform_matrix_offset_center ( matrix , y , x ) :
    """Convert the matrix from Cartesian coordinates ( the origin in the middle of image ) to Image coordinates ( the origin on the top - left of image ) .
 Parameters
 matrix : numpy . array
 Transform matrix .
 x and y : 2 int
 Size of image .
 Returns
 numpy . array
 The transform matrix .
 Examples
 - See ` ` tl . prepro . rotation ` ` , ` ` tl . prepro . shear ` ` , ` ` tl . prepro . zoom ` ` ."""

implementation:
o_x = ( x - 1 ) / 2.0
o_y = ( y - 1 ) / 2.0
offset_matrix = np . array ( [ [ 1 , 0 , o_x ] , [ 0 , 1 , o_y ] , [ 0 , 0 , 1 ] ] )
reset_matrix = np . array ( [ [ 1 , 0 , - o_x ] , [ 0 , 1 , - o_y ] , [ 0 , 0 , 1 ] ] )
transform_matrix = np . dot ( np . dot ( offset_matrix , matrix ) , reset_matrix )
return transform_matrix


signature:
def affine_transform ( x , transform_matrix , channel_index = 2 , fill_mode = 'nearest' , cval = 0. , order = 1 ) :
    """Return transformed images by given an affine matrix in Scipy format ( x is height ) .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 transform _ matrix : numpy . array
 Transform matrix ( offset center ) , can be generated by ` ` transform _ matrix _ offset _ center ` `
 channel _ index : int
 Index of channel , default 2.
 fill _ mode : str
 Method to fill missing pixel , default ` nearest ` , more options ` constant ` , ` reflect ` or ` wrap ` , see ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 cval : float
 Value used for points outside the boundaries of the input if mode = ' constant ' . Default is 0.0
 order : int
 The order of interpolation . The order has to be in the range 0-5:
 - 0 Nearest - neighbor
 - 1 Bi - linear ( default )
 - 2 Bi - quadratic
 - 3 Bi - cubic
 - 4 Bi - quartic
 - 5 Bi - quintic
 - ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 Returns
 numpy . array
 A processed image .
 Examples
 > > > M _ shear = tl . prepro . affine _ shear _ matrix ( intensity = 0.2 , is _ random = False )
 > > > M _ zoom = tl . prepro . affine _ zoom _ matrix ( zoom _ range = 0.8)
 > > > M _ combined = M _ shear . dot ( M _ zoom )
 > > > transform _ matrix = tl . prepro . transform _ matrix _ offset _ center ( M _ combined , h , w )
 > > > result = tl . prepro . affine _ transform ( image , transform _ matrix )"""

implementation:
# transform _ matrix = transform _ matrix _ offset _ center ( )
# asdihasid
# asd
x = np . rollaxis ( x , channel_index , 0 )
final_affine_matrix = transform_matrix [ : 2 , : 2 ]
final_offset = transform_matrix [ : 2 , 2 ]
channel_images = [ ndi . interpolation . affine_transform ( x_channel , final_affine_matrix , final_offset , order = order , mode = fill_mode , cval = cval ) for x_channel in x ]
x = np . stack ( channel_images , axis = 0 )
x = np . rollaxis ( x , 0 , channel_index + 1 )
return x


signature:
def affine_transform_cv2 ( x , transform_matrix , flags = None , border_mode = 'constant' ) :
    """Return transformed images by given an affine matrix in OpenCV format ( x is width ) . ( Powered by OpenCV2 , faster than ` ` tl . prepro . affine _ transform ` ` )
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 transform _ matrix : numpy . array
 A transform matrix , OpenCV format .
 border _ mode : str
 - ` constant ` , pad the image with a constant value ( i . e . black or 0)
 - ` replicate ` , the row or column at the very edge of the original is replicated to the extra border .
 Examples
 > > > M _ shear = tl . prepro . affine _ shear _ matrix ( intensity = 0.2 , is _ random = False )
 > > > M _ zoom = tl . prepro . affine _ zoom _ matrix ( zoom _ range = 0.8)
 > > > M _ combined = M _ shear . dot ( M _ zoom )
 > > > result = tl . prepro . affine _ transform _ cv2 ( image , M _ combined )"""

implementation:
rows , cols = x . shape [ 0 ] , x . shape [ 1 ]
if flags is None :
    flags = cv2 . INTER_AREA
if border_mode is 'constant' :
    border_mode = cv2 . BORDER_CONSTANT
elif border_mode is 'replicate' :
    border_mode = cv2 . BORDER_REPLICATE
else :
    raise Exception ( "unsupport border_mode, check cv.BORDER_ for more details." )
return cv2 . warpAffine ( x , transform_matrix [ 0 : 2 , : ] , ( cols , rows ) , flags = flags , borderMode = border_mode )


signature:
def affine_transform_keypoints ( coords_list , transform_matrix ) :
    """Transform keypoint coordinates according to a given affine transform matrix .
 OpenCV format , x is width .
 Note that , for pose estimation task , flipping requires maintaining the left and right body information .
 We should not flip the left and right body , so please use ` ` tl . prepro . keypoint _ random _ flip ` ` .
 Parameters
 coords _ list : list of list of tuple / list
 The coordinates
 e . g . , the keypoint coordinates of every person in an image .
 transform _ matrix : numpy . array
 Transform matrix , OpenCV format .
 Examples
 > > > # 1 . get all affine transform matrices
 > > > M _ rotate = tl . prepro . affine _ rotation _ matrix ( angle = 20)
 > > > M _ flip = tl . prepro . affine _ horizontal _ flip _ matrix ( prob = 1)
 > > > # 2 . combine all affine transform matrices to one matrix
 > > > M _ combined = dot ( M _ flip ) . dot ( M _ rotate )
 > > > # 3 . transfrom the matrix from Cartesian coordinate ( the origin in the middle of image )
 > > > # to Image coordinate ( the origin on the top - left of image )
 > > > transform _ matrix = tl . prepro . transform _ matrix _ offset _ center ( M _ combined , x = w , y = h )
 > > > # 4 . then we can transfrom the image once for all transformations
 > > > result = tl . prepro . affine _ transform _ cv2 ( image , transform _ matrix ) # 76 times faster
 > > > # 5 . transform keypoint coordinates
 > > > coords = [ [ ( 50 , 100 ) , ( 100 , 100 ) , ( 100 , 50 ) , ( 200 , 200 ) ] , [ ( 250 , 50 ) , ( 200 , 50 ) , ( 200 , 100 ) ] ]
 > > > coords _ result = tl . prepro . affine _ transform _ keypoints ( coords , transform _ matrix )"""

implementation:
coords_result_list = [ ]
for coords in coords_list :
    coords = np . asarray ( coords )
    coords = coords . transpose ( [ 1 , 0 ] )
    coords = np . insert ( coords , 2 , 1 , axis = 0 )
    # print ( coords )
    # print ( transform _ matrix )
    coords_result = np . matmul ( transform_matrix , coords )
    coords_result = coords_result [ 0 : 2 , : ] . transpose ( [ 1 , 0 ] )
    coords_result_list . append ( coords_result )
return coords_result_list


signature:
def projective_transform_by_points ( x , src , dst , map_args = None , output_shape = None , order = 1 , mode = 'constant' , cval = 0.0 , clip = True , preserve_range = False ) :
    """Projective transform by given coordinates , usually 4 coordinates .
 see ` scikit - image < http : / / scikit - image . org / docs / dev / auto _ examples / applications / plot _ geometric . html > ` _ _ .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 src : list or numpy
 The original coordinates , usually 4 coordinates of ( width , height ) .
 dst : list or numpy
 The coordinates after transformation , the number of coordinates is the same with src .
 map _ args : dictionary or None
 Keyword arguments passed to inverse map .
 output _ shape : tuple of 2 int
 Shape of the output image generated . By default the shape of the input image is preserved . Note that , even for multi - band images , only rows and columns need to be specified .
 order : int
 The order of interpolation . The order has to be in the range 0-5:
 - 0 Nearest - neighbor
 - 1 Bi - linear ( default )
 - 2 Bi - quadratic
 - 3 Bi - cubic
 - 4 Bi - quartic
 - 5 Bi - quintic
 mode : str
 One of ` constant ` ( default ) , ` edge ` , ` symmetric ` , ` reflect ` or ` wrap ` .
 Points outside the boundaries of the input are filled according to the given mode . Modes match the behaviour of numpy . pad .
 cval : float
 Used in conjunction with mode ` constant ` , the value outside the image boundaries .
 clip : boolean
 Whether to clip the output to the range of values of the input image . This is enabled by default , since higher order interpolation may produce values outside the given input range .
 preserve _ range : boolean
 Whether to keep the original range of values . Otherwise , the input image is converted according to the conventions of img _ as _ float .
 Returns
 numpy . array
 A processed image .
 Examples
 Assume X is an image from CIFAR - 10 , i . e . shape = = ( 32 , 32 , 3)
 > > > src = [ [ 0,0 ] , [ 0,32 ] , [ 32,0 ] , [ 32,32 ] ] # [ w , h ]
 > > > dst = [ [ 10,10 ] , [ 0,32 ] , [ 32,0 ] , [ 32,32 ] ]
 > > > x = tl . prepro . projective _ transform _ by _ points ( X , src , dst )
 References
 - ` scikit - image : geometric transformations < http : / / scikit - image . org / docs / dev / auto _ examples / applications / plot _ geometric . html > ` _ _
 - ` scikit - image : examples < http : / / scikit - image . org / docs / dev / auto _ examples / index . html > ` _ _"""

implementation:
if map_args is None :
    map_args = { }
# if type ( src ) is list :
if isinstance ( src , list ) : # convert to numpy
    src = np . array ( src )
# if type ( dst ) is list :
if isinstance ( dst , list ) :
    dst = np . array ( dst )
if np . max ( x ) > 1 : # convert to [ 0 , 1]
    x = x / 255
m = transform . ProjectiveTransform ( )
m . estimate ( dst , src )
warped = transform . warp ( x , m , map_args = map_args , output_shape = output_shape , order = order , mode = mode , cval = cval , clip = clip , preserve_range = preserve_range )
return warped


signature:
def rotation ( x , rg = 20 , is_random = False , row_index = 0 , col_index = 1 , channel_index = 2 , fill_mode = 'nearest' , cval = 0. , order = 1 ) :
    """Rotate an image randomly or non - randomly .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 rg : int or float
 Degree to rotate , usually 0 ~ 180.
 is _ random : boolean
 If True , randomly rotate . Default is False
 row _ index col _ index and channel _ index : int
 Index of row , col and channel , default ( 0 , 1 , 2 ) , for theano ( 1 , 2 , 0 ) .
 fill _ mode : str
 Method to fill missing pixel , default ` nearest ` , more options ` constant ` , ` reflect ` or ` wrap ` , see ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 cval : float
 Value used for points outside the boundaries of the input if mode = ` constant ` . Default is 0.0
 order : int
 The order of interpolation . The order has to be in the range 0-5 . See ` ` tl . prepro . affine _ transform ` ` and ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 Returns
 numpy . array
 A processed image .
 Examples
 > > > x - - > [ row , col , 1]
 > > > x = tl . prepro . rotation ( x , rg = 40 , is _ random = False )
 > > > tl . vis . save _ image ( x , ' im . png ' )"""

implementation:
if is_random :
    theta = np . pi / 180 * np . random . uniform ( - rg , rg )
else :
    theta = np . pi / 180 * rg
rotation_matrix = np . array ( [ [ np . cos ( theta ) , - np . sin ( theta ) , 0 ] , [ np . sin ( theta ) , np . cos ( theta ) , 0 ] , [ 0 , 0 , 1 ] ] )
h , w = x . shape [ row_index ] , x . shape [ col_index ]
transform_matrix = transform_matrix_offset_center ( rotation_matrix , h , w )
x = affine_transform ( x , transform_matrix , channel_index , fill_mode , cval , order )
return x


signature:
def crop ( x , wrg , hrg , is_random = False , row_index = 0 , col_index = 1 ) :
    """Randomly or centrally crop an image .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 wrg : int
 Size of width .
 hrg : int
 Size of height .
 is _ random : boolean ,
 If True , randomly crop , else central crop . Default is False .
 row _ index : int
 index of row .
 col _ index : int
 index of column .
 Returns
 numpy . array
 A processed image ."""

implementation:
h , w = x . shape [ row_index ] , x . shape [ col_index ]
if ( h < hrg ) or ( w < wrg ) :
    raise AssertionError ( "The size of cropping should smaller than or equal to the original image" )
if is_random :
    h_offset = int ( np . random . uniform ( 0 , h - hrg ) )
    w_offset = int ( np . random . uniform ( 0 , w - wrg ) )
    # tl . logging . info ( h _ offset , w _ offset , x [ h _ offset : hrg + h _ offset , w _ offset : wrg + w _ offset ] . shape )
    return x [ h_offset : hrg + h_offset , w_offset : wrg + w_offset ]
else : # central crop
    h_offset = int ( np . floor ( ( h - hrg ) / 2. ) )
    w_offset = int ( np . floor ( ( w - wrg ) / 2. ) )
    h_end = h_offset + hrg
    w_end = w_offset + wrg
    return x [ h_offset : h_end , w_offset : w_end ]


signature:
def crop_multi ( x , wrg , hrg , is_random = False , row_index = 0 , col_index = 1 ) :
    """Randomly or centrally crop multiple images .
 Parameters
 x : list of numpy . array
 List of images with dimension of [ n _ images , row , col , channel ] ( default ) .
 others : args
 See ` ` tl . prepro . crop ` ` .
 Returns
 numpy . array
 A list of processed images ."""

implementation:
h , w = x [ 0 ] . shape [ row_index ] , x [ 0 ] . shape [ col_index ]
if ( h < hrg ) or ( w < wrg ) :
    raise AssertionError ( "The size of cropping should smaller than or equal to the original image" )
if is_random :
    h_offset = int ( np . random . uniform ( 0 , h - hrg ) )
    w_offset = int ( np . random . uniform ( 0 , w - wrg ) )
    results = [ ]
    for data in x :
        results . append ( data [ h_offset : hrg + h_offset , w_offset : wrg + w_offset ] )
    return np . asarray ( results )
else : # central crop
    h_offset = ( h - hrg ) / 2
    w_offset = ( w - wrg ) / 2
    results = [ ]
    for data in x :
        results . append ( data [ h_offset : h - h_offset , w_offset : w - w_offset ] )
    return np . asarray ( results )


signature:
def flip_axis ( x , axis = 1 , is_random = False ) :
    """Flip the axis of an image , such as flip left and right , up and down , randomly or non - randomly ,
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 axis : int
 Which axis to flip .
 - 0 , flip up and down
 - 1 , flip left and right
 - 2 , flip channel
 is _ random : boolean
 If True , randomly flip . Default is False .
 Returns
 numpy . array
 A processed image ."""

implementation:
if is_random :
    factor = np . random . uniform ( - 1 , 1 )
    if factor > 0 :
        x = np . asarray ( x ) . swapaxes ( axis , 0 )
        x = x [ : : - 1 , ... ]
        x = x . swapaxes ( 0 , axis )
        return x
    else :
        return x
else :
    x = np . asarray ( x ) . swapaxes ( axis , 0 )
    x = x [ : : - 1 , ... ]
    x = x . swapaxes ( 0 , axis )
    return x


signature:
def flip_axis_multi ( x , axis , is_random = False ) :
    """Flip the axises of multiple images together , such as flip left and right , up and down , randomly or non - randomly ,
 Parameters
 x : list of numpy . array
 List of images with dimension of [ n _ images , row , col , channel ] ( default ) .
 others : args
 See ` ` tl . prepro . flip _ axis ` ` .
 Returns
 numpy . array
 A list of processed images ."""

implementation:
if is_random :
    factor = np . random . uniform ( - 1 , 1 )
    if factor > 0 : # x = np . asarray ( x ) . swapaxes ( axis , 0)
    # x = x [ : : - 1 , . . . ]
    # x = x . swapaxes ( 0 , axis )
    # return x
        results = [ ]
        for data in x :
            data = np . asarray ( data ) . swapaxes ( axis , 0 )
            data = data [ : : - 1 , ... ]
            data = data . swapaxes ( 0 , axis )
            results . append ( data )
        return np . asarray ( results )
    else :
        return np . asarray ( x )
else : # x = np . asarray ( x ) . swapaxes ( axis , 0)
# x = x [ : : - 1 , . . . ]
# x = x . swapaxes ( 0 , axis )
# return x
    results = [ ]
    for data in x :
        data = np . asarray ( data ) . swapaxes ( axis , 0 )
        data = data [ : : - 1 , ... ]
        data = data . swapaxes ( 0 , axis )
        results . append ( data )
    return np . asarray ( results )


signature:
def shift ( x , wrg = 0.1 , hrg = 0.1 , is_random = False , row_index = 0 , col_index = 1 , channel_index = 2 , fill_mode = 'nearest' , cval = 0. , order = 1 ) :
    """Shift an image randomly or non - randomly .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 wrg : float
 Percentage of shift in axis x , usually - 0.25 ~ 0.25.
 hrg : float
 Percentage of shift in axis y , usually - 0.25 ~ 0.25.
 is _ random : boolean
 If True , randomly shift . Default is False .
 row _ index col _ index and channel _ index : int
 Index of row , col and channel , default ( 0 , 1 , 2 ) , for theano ( 1 , 2 , 0 ) .
 fill _ mode : str
 Method to fill missing pixel , default ` nearest ` , more options ` constant ` , ` reflect ` or ` wrap ` , see ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 cval : float
 Value used for points outside the boundaries of the input if mode = ' constant ' . Default is 0.0.
 order : int
 The order of interpolation . The order has to be in the range 0-5 . See ` ` tl . prepro . affine _ transform ` ` and ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 Returns
 numpy . array
 A processed image ."""

implementation:
h , w = x . shape [ row_index ] , x . shape [ col_index ]
if is_random :
    tx = np . random . uniform ( - hrg , hrg ) * h
    ty = np . random . uniform ( - wrg , wrg ) * w
else :
    tx , ty = hrg * h , wrg * w
translation_matrix = np . array ( [ [ 1 , 0 , tx ] , [ 0 , 1 , ty ] , [ 0 , 0 , 1 ] ] )
transform_matrix = translation_matrix
# no need to do offset
x = affine_transform ( x , transform_matrix , channel_index , fill_mode , cval , order )
return x


signature:
def shift_multi ( x , wrg = 0.1 , hrg = 0.1 , is_random = False , row_index = 0 , col_index = 1 , channel_index = 2 , fill_mode = 'nearest' , cval = 0. , order = 1 ) :
    """Shift images with the same arguments , randomly or non - randomly .
 Usually be used for image segmentation which x = [ X , Y ] , X and Y should be matched .
 Parameters
 x : list of numpy . array
 List of images with dimension of [ n _ images , row , col , channel ] ( default ) .
 others : args
 See ` ` tl . prepro . shift ` ` .
 Returns
 numpy . array
 A list of processed images ."""

implementation:
h , w = x [ 0 ] . shape [ row_index ] , x [ 0 ] . shape [ col_index ]
if is_random :
    tx = np . random . uniform ( - hrg , hrg ) * h
    ty = np . random . uniform ( - wrg , wrg ) * w
else :
    tx , ty = hrg * h , wrg * w
translation_matrix = np . array ( [ [ 1 , 0 , tx ] , [ 0 , 1 , ty ] , [ 0 , 0 , 1 ] ] )
transform_matrix = translation_matrix
# no need to do offset
results = [ ]
for data in x :
    results . append ( affine_transform ( data , transform_matrix , channel_index , fill_mode , cval , order ) )
return np . asarray ( results )


signature:
def shear ( x , intensity = 0.1 , is_random = False , row_index = 0 , col_index = 1 , channel_index = 2 , fill_mode = 'nearest' , cval = 0. , order = 1 ) :
    """Shear an image randomly or non - randomly .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 intensity : float
 Percentage of shear , usually - 0.5 ~ 0.5 ( is _ random = = True ) , 0 ~ 0.5 ( is _ random = = False ) ,
 you can have a quick try by shear ( X , 1 ) .
 is _ random : boolean
 If True , randomly shear . Default is False .
 row _ index col _ index and channel _ index : int
 Index of row , col and channel , default ( 0 , 1 , 2 ) , for theano ( 1 , 2 , 0 ) .
 fill _ mode : str
 Method to fill missing pixel , default ` nearest ` , more options ` constant ` , ` reflect ` or ` wrap ` , see and ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 cval : float
 Value used for points outside the boundaries of the input if mode = ' constant ' . Default is 0.0.
 order : int
 The order of interpolation . The order has to be in the range 0-5 . See ` ` tl . prepro . affine _ transform ` ` and ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 Returns
 numpy . array
 A processed image .
 References
 - ` Affine transformation < https : / / uk . mathworks . com / discovery / affine - transformation . html > ` _ _"""

implementation:
if is_random :
    shear = np . random . uniform ( - intensity , intensity )
else :
    shear = intensity
shear_matrix = np . array ( [ [ 1 , - np . sin ( shear ) , 0 ] , [ 0 , np . cos ( shear ) , 0 ] , [ 0 , 0 , 1 ] ] )
h , w = x . shape [ row_index ] , x . shape [ col_index ]
transform_matrix = transform_matrix_offset_center ( shear_matrix , h , w )
x = affine_transform ( x , transform_matrix , channel_index , fill_mode , cval , order )
return x


signature:
def shear2 ( x , shear = ( 0.1 , 0.1 ) , is_random = False , row_index = 0 , col_index = 1 , channel_index = 2 , fill_mode = 'nearest' , cval = 0. , order = 1 ) :
    """Shear an image randomly or non - randomly .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 shear : tuple of two floats
 Percentage of shear for height and width direction ( 0 , 1 ) .
 is _ random : boolean
 If True , randomly shear . Default is False .
 row _ index col _ index and channel _ index : int
 Index of row , col and channel , default ( 0 , 1 , 2 ) , for theano ( 1 , 2 , 0 ) .
 fill _ mode : str
 Method to fill missing pixel , default ` nearest ` , more options ` constant ` , ` reflect ` or ` wrap ` , see ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 cval : float
 Value used for points outside the boundaries of the input if mode = ' constant ' . Default is 0.0.
 order : int
 The order of interpolation . The order has to be in the range 0-5 . See ` ` tl . prepro . affine _ transform ` ` and ` scipy ndimage affine _ transform < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . interpolation . affine _ transform . html > ` _ _
 Returns
 numpy . array
 A processed image .
 References
 - ` Affine transformation < https : / / uk . mathworks . com / discovery / affine - transformation . html > ` _ _"""

implementation:
if len ( shear ) != 2 :
    raise AssertionError ( "shear should be tuple of 2 floats, or you want to use tl.prepro.shear rather than tl.prepro.shear2 ?" )
if isinstance ( shear , tuple ) :
    shear = list ( shear )
if is_random :
    shear [ 0 ] = np . random . uniform ( - shear [ 0 ] , shear [ 0 ] )
    shear [ 1 ] = np . random . uniform ( - shear [ 1 ] , shear [ 1 ] )
shear_matrix = np . array ( [ [ 1 , shear [ 0 ] , 0 ] , [ shear [ 1 ] , 1 , 0 ] , [ 0 , 0 , 1 ] ] )
h , w = x . shape [ row_index ] , x . shape [ col_index ]
transform_matrix = transform_matrix_offset_center ( shear_matrix , h , w )
x = affine_transform ( x , transform_matrix , channel_index , fill_mode , cval , order )
return x


signature:
def swirl ( x , center = None , strength = 1 , radius = 100 , rotation = 0 , output_shape = None , order = 1 , mode = 'constant' , cval = 0 , clip = True , preserve_range = False , is_random = False ) :
    """Swirl an image randomly or non - randomly , see ` scikit - image swirl API < http : / / scikit - image . org / docs / dev / api / skimage . transform . html # skimage . transform . swirl > ` _ _
 and ` example < http : / / scikit - image . org / docs / dev / auto _ examples / plot _ swirl . html > ` _ _ .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 center : tuple or 2 int or None
 Center coordinate of transformation ( optional ) .
 strength : float
 The amount of swirling applied .
 radius : float
 The extent of the swirl in pixels . The effect dies out rapidly beyond radius .
 rotation : float
 Additional rotation applied to the image , usually [ 0 , 360 ] , relates to center .
 output _ shape : tuple of 2 int or None
 Shape of the output image generated ( height , width ) . By default the shape of the input image is preserved .
 order : int , optional
 The order of the spline interpolation , default is 1 . The order has to be in the range 0-5 . See skimage . transform . warp for detail .
 mode : str
 One of ` constant ` ( default ) , ` edge ` , ` symmetric ` ` reflect ` and ` wrap ` .
 Points outside the boundaries of the input are filled according to the given mode , with ` constant ` used as the default . Modes match the behaviour of numpy . pad .
 cval : float
 Used in conjunction with mode ` constant ` , the value outside the image boundaries .
 clip : boolean
 Whether to clip the output to the range of values of the input image . This is enabled by default , since higher order interpolation may produce values outside the given input range .
 preserve _ range : boolean
 Whether to keep the original range of values . Otherwise , the input image is converted according to the conventions of img _ as _ float .
 is _ random : boolean ,
 If True , random swirl . Default is False .
 - random center = [ ( 0 ~ x . shape [ 0 ] ) , ( 0 ~ x . shape [ 1 ] ) ]
 - random strength = [ 0 , strength ]
 - random radius = [ 1e - 10 , radius ]
 - random rotation = [ - rotation , rotation ]
 Returns
 numpy . array
 A processed image .
 Examples
 > > > x - - > [ row , col , 1 ] greyscale
 > > > x = tl . prepro . swirl ( x , strength = 4 , radius = 100)"""

implementation:
if radius == 0 :
    raise AssertionError ( "Invalid radius value" )
rotation = np . pi / 180 * rotation
if is_random :
    center_h = int ( np . random . uniform ( 0 , x . shape [ 0 ] ) )
    center_w = int ( np . random . uniform ( 0 , x . shape [ 1 ] ) )
    center = ( center_h , center_w )
    strength = np . random . uniform ( 0 , strength )
    radius = np . random . uniform ( 1e-10 , radius )
    rotation = np . random . uniform ( - rotation , rotation )
max_v = np . max ( x )
if max_v > 1 : # Note : the input of this fn should be [ - 1 , 1 ] , rescale is required .
    x = x / max_v
swirled = skimage . transform . swirl ( x , center = center , strength = strength , radius = radius , rotation = rotation , output_shape = output_shape , order = order , mode = mode , cval = cval , clip = clip , preserve_range = preserve_range )
if max_v > 1 :
    swirled = swirled * max_v
return swirled


signature:
def elastic_transform ( x , alpha , sigma , mode = "constant" , cval = 0 , is_random = False ) :
    """Elastic transformation for image as described in ` [ Simard2003 ] < http : / / deeplearning . cs . cmu . edu / pdfs / Simard . pdf > ` _ _ .
 Parameters
 x : numpy . array
 A greyscale image .
 alpha : float
 Alpha value for elastic transformation .
 sigma : float or sequence of float
 The smaller the sigma , the more transformation . Standard deviation for Gaussian kernel . The standard deviations of the Gaussian filter are given for each axis as a sequence , or as a single number , in which case it is equal for all axes .
 mode : str
 See ` scipy . ndimage . filters . gaussian _ filter < https : / / docs . scipy . org / doc / scipy - 0.14.0 / reference / generated / scipy . ndimage . filters . gaussian _ filter . html > ` _ _ . Default is ` constant ` .
 cval : float ,
 Used in conjunction with ` mode ` of ` constant ` , the value outside the image boundaries .
 is _ random : boolean
 Default is False .
 Returns
 numpy . array
 A processed image .
 Examples
 > > > x = tl . prepro . elastic _ transform ( x , alpha = x . shape [ 1 ] * 3 , sigma = x . shape [ 1 ] * 0.07)
 References
 - ` Github < https : / / gist . github . com / chsasank / 4d8f68caf01f041a6453e67fb30f8f5a > ` _ _ .
 - ` Kaggle < https : / / www . kaggle . com / pscion / ultrasound - nerve - segmentation / elastic - transform - for - data - augmentation - 0878921a > ` _ _"""

implementation:
if is_random is False :
    random_state = np . random . RandomState ( None )
else :
    random_state = np . random . RandomState ( int ( time . time ( ) ) )
is_3d = False
if len ( x . shape ) == 3 and x . shape [ - 1 ] == 1 :
    x = x [ : , : , 0 ]
    is_3d = True
elif len ( x . shape ) == 3 and x . shape [ - 1 ] != 1 :
    raise Exception ( "Only support greyscale image" )
if len ( x . shape ) != 2 :
    raise AssertionError ( "input should be grey-scale image" )
shape = x . shape
dx = gaussian_filter ( ( random_state . rand ( * shape ) * 2 - 1 ) , sigma , mode = mode , cval = cval ) * alpha
dy = gaussian_filter ( ( random_state . rand ( * shape ) * 2 - 1 ) , sigma , mode = mode , cval = cval ) * alpha
x_ , y_ = np . meshgrid ( np . arange ( shape [ 0 ] ) , np . arange ( shape [ 1 ] ) , indexing = 'ij' )
indices = np . reshape ( x_ + dx , ( - 1 , 1 ) ) , np . reshape ( y_ + dy , ( - 1 , 1 ) )
if is_3d :
    return map_coordinates ( x , indices , order = 1 ) . reshape ( ( shape [ 0 ] , shape [ 1 ] , 1 ) )
else :
    return map_coordinates ( x , indices , order = 1 ) . reshape ( shape )


signature:
def zoom ( x , zoom_range = ( 0.9 , 1.1 ) , flags = None , border_mode = 'constant' ) :
    """Zooming / Scaling a single image that height and width are changed together .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 zoom _ range : float or tuple of 2 floats
 The zooming / scaling ratio , greater than 1 means larger .
 - float , a fixed ratio .
 - tuple of 2 floats , randomly sample a value as the ratio between 2 values .
 border _ mode : str
 - ` constant ` , pad the image with a constant value ( i . e . black or 0)
 - ` replicate ` , the row or column at the very edge of the original is replicated to the extra border .
 Returns
 numpy . array
 A processed image ."""

implementation:
zoom_matrix = affine_zoom_matrix ( zoom_range = zoom_range )
h , w = x . shape [ 0 ] , x . shape [ 1 ]
transform_matrix = transform_matrix_offset_center ( zoom_matrix , h , w )
x = affine_transform_cv2 ( x , transform_matrix , flags = flags , border_mode = border_mode )
return x


signature:
def respective_zoom ( x , h_range = ( 0.9 , 1.1 ) , w_range = ( 0.9 , 1.1 ) , flags = None , border_mode = 'constant' ) :
    """Zooming / Scaling a single image that height and width are changed independently .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 h _ range : float or tuple of 2 floats
 The zooming / scaling ratio of height , greater than 1 means larger .
 - float , a fixed ratio .
 - tuple of 2 floats , randomly sample a value as the ratio between 2 values .
 w _ range : float or tuple of 2 floats
 The zooming / scaling ratio of width , greater than 1 means larger .
 - float , a fixed ratio .
 - tuple of 2 floats , randomly sample a value as the ratio between 2 values .
 border _ mode : str
 - ` constant ` , pad the image with a constant value ( i . e . black or 0)
 - ` replicate ` , the row or column at the very edge of the original is replicated to the extra border .
 Returns
 numpy . array
 A processed image ."""

implementation:
zoom_matrix = affine_respective_zoom_matrix ( h_range = h_range , w_range = w_range )
h , w = x . shape [ 0 ] , x . shape [ 1 ]
transform_matrix = transform_matrix_offset_center ( zoom_matrix , h , w )
x = affine_transform_cv2 ( x , transform_matrix , flags = flags , border_mode = border_mode )
# affine _ transform ( x , transform _ matrix , channel _ index , fill _ mode , cval , order )
return x


signature:
def zoom_multi ( x , zoom_range = ( 0.9 , 1.1 ) , flags = None , border_mode = 'constant' ) :
    """Zoom in and out of images with the same arguments , randomly or non - randomly .
 Usually be used for image segmentation which x = [ X , Y ] , X and Y should be matched .
 Parameters
 x : list of numpy . array
 List of images with dimension of [ n _ images , row , col , channel ] ( default ) .
 others : args
 See ` ` tl . prepro . zoom ` ` .
 Returns
 numpy . array
 A list of processed images ."""

implementation:
zoom_matrix = affine_zoom_matrix ( zoom_range = zoom_range )
results = [ ]
for img in x :
    h , w = x . shape [ 0 ] , x . shape [ 1 ]
    transform_matrix = transform_matrix_offset_center ( zoom_matrix , h , w )
    results . append ( affine_transform_cv2 ( x , transform_matrix , flags = flags , border_mode = border_mode ) )
return result


signature:
def brightness ( x , gamma = 1 , gain = 1 , is_random = False ) :
    """Change the brightness of a single image , randomly or non - randomly .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 gamma : float
 Non negative real number . Default value is 1.
 - Small than 1 means brighter .
 - If ` is _ random ` is True , gamma in a range of ( 1 - gamma , 1 + gamma ) .
 gain : float
 The constant multiplier . Default value is 1.
 is _ random : boolean
 If True , randomly change brightness . Default is False .
 Returns
 numpy . array
 A processed image .
 References
 - ` skimage . exposure . adjust _ gamma < http : / / scikit - image . org / docs / dev / api / skimage . exposure . html > ` _ _
 - ` chinese blog < http : / / www . cnblogs . com / denny402 / p / 5124402 . html > ` _ _"""

implementation:
if is_random :
    gamma = np . random . uniform ( 1 - gamma , 1 + gamma )
x = exposure . adjust_gamma ( x , gamma , gain )
return x


signature:
def brightness_multi ( x , gamma = 1 , gain = 1 , is_random = False ) :
    """Change the brightness of multiply images , randomly or non - randomly .
 Usually be used for image segmentation which x = [ X , Y ] , X and Y should be matched .
 Parameters
 x : list of numpyarray
 List of images with dimension of [ n _ images , row , col , channel ] ( default ) .
 others : args
 See ` ` tl . prepro . brightness ` ` .
 Returns
 numpy . array
 A list of processed images ."""

implementation:
if is_random :
    gamma = np . random . uniform ( 1 - gamma , 1 + gamma )
results = [ ]
for data in x :
    results . append ( exposure . adjust_gamma ( data , gamma , gain ) )
return np . asarray ( results )


signature:
def illumination ( x , gamma = 1. , contrast = 1. , saturation = 1. , is_random = False ) :
    """Perform illumination augmentation for a single image , randomly or non - randomly .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 gamma : float
 Change brightness ( the same with ` ` tl . prepro . brightness ` ` )
 - if is _ random = False , one float number , small than one means brighter , greater than one means darker .
 - if is _ random = True , tuple of two float numbers , ( min , max ) .
 contrast : float
 Change contrast .
 - if is _ random = False , one float number , small than one means blur .
 - if is _ random = True , tuple of two float numbers , ( min , max ) .
 saturation : float
 Change saturation .
 - if is _ random = False , one float number , small than one means unsaturation .
 - if is _ random = True , tuple of two float numbers , ( min , max ) .
 is _ random : boolean
 If True , randomly change illumination . Default is False .
 Returns
 numpy . array
 A processed image .
 Examples
 Random
 > > > x = tl . prepro . illumination ( x , gamma = ( 0.5 , 5.0 ) , contrast = ( 0.3 , 1.0 ) , saturation = ( 0.7 , 1.0 ) , is _ random = True )
 Non - random
 > > > x = tl . prepro . illumination ( x , 0.5 , 0.6 , 0.8 , is _ random = False )"""

implementation:
if is_random :
    if not ( len ( gamma ) == len ( contrast ) == len ( saturation ) == 2 ) :
        raise AssertionError ( "if is_random = True, the arguments are (min, max)" )
    # # random change brightness # small - - > brighter
    illum_settings = np . random . randint ( 0 , 3 )
    # 0 - brighter , 1 - darker , 2 keep normal
    if illum_settings == 0 : # brighter
        gamma = np . random . uniform ( gamma [ 0 ] , 1.0 )
        # ( . 5 , 1.0)
    elif illum_settings == 1 : # darker
        gamma = np . random . uniform ( 1.0 , gamma [ 1 ] )
        # (1.0 , 5.0)
    else :
        gamma = 1
    im_ = brightness ( x , gamma = gamma , gain = 1 , is_random = False )
    # tl . logging . info ( " using contrast and saturation " )
    image = PIL . Image . fromarray ( im_ )
    # array - > PIL
    contrast_adjust = PIL . ImageEnhance . Contrast ( image )
    image = contrast_adjust . enhance ( np . random . uniform ( contrast [ 0 ] , contrast [ 1 ] ) )
    # 0.3,0.9 ) )
    saturation_adjust = PIL . ImageEnhance . Color ( image )
    image = saturation_adjust . enhance ( np . random . uniform ( saturation [ 0 ] , saturation [ 1 ] ) )
    # (0.7,1.0 ) )
    im_ = np . array ( image )
    # PIL - > array
else :
    im_ = brightness ( x , gamma = gamma , gain = 1 , is_random = False )
    image = PIL . Image . fromarray ( im_ )
    # array - > PIL
    contrast_adjust = PIL . ImageEnhance . Contrast ( image )
    image = contrast_adjust . enhance ( contrast )
    saturation_adjust = PIL . ImageEnhance . Color ( image )
    image = saturation_adjust . enhance ( saturation )
    im_ = np . array ( image )
    # PIL - > array
return np . asarray ( im_ )


signature:
def rgb_to_hsv ( rgb ) :
    """Input RGB image [ 0 ~ 255 ] return HSV image [ 0 ~ 1 ] .
 Parameters
 rgb : numpy . array
 An image with values between 0 and 255.
 Returns
 numpy . array
 A processed image ."""

implementation:
# Translated from source of colorsys . rgb _ to _ hsv
# r , g , b should be a numpy arrays with values between 0 and 255
# rgb _ to _ hsv returns an array of floats between 0.0 and 1.0.
rgb = rgb . astype ( 'float' )
hsv = np . zeros_like ( rgb )
# in case an RGBA array was passed , just copy the A channel
hsv [ ... , 3 : ] = rgb [ ... , 3 : ]
r , g , b = rgb [ ... , 0 ] , rgb [ ... , 1 ] , rgb [ ... , 2 ]
maxc = np . max ( rgb [ ... , : 3 ] , axis = - 1 )
minc = np . min ( rgb [ ... , : 3 ] , axis = - 1 )
hsv [ ... , 2 ] = maxc
mask = maxc != minc
hsv [ mask , 1 ] = ( maxc - minc ) [ mask ] / maxc [ mask ]
rc = np . zeros_like ( r )
gc = np . zeros_like ( g )
bc = np . zeros_like ( b )
rc [ mask ] = ( maxc - r ) [ mask ] / ( maxc - minc ) [ mask ]
gc [ mask ] = ( maxc - g ) [ mask ] / ( maxc - minc ) [ mask ]
bc [ mask ] = ( maxc - b ) [ mask ] / ( maxc - minc ) [ mask ]
hsv [ ... , 0 ] = np . select ( [ r == maxc , g == maxc ] , [ bc - gc , 2.0 + rc - bc ] , default = 4.0 + gc - rc )
hsv [ ... , 0 ] = ( hsv [ ... , 0 ] / 6.0 ) % 1.0
return hsv


signature:
def hsv_to_rgb ( hsv ) :
    """Input HSV image [ 0 ~ 1 ] return RGB image [ 0 ~ 255 ] .
 Parameters
 hsv : numpy . array
 An image with values between 0.0 and 1.0
 Returns
 numpy . array
 A processed image ."""

implementation:
# Translated from source of colorsys . hsv _ to _ rgb
# h , s should be a numpy arrays with values between 0.0 and 1.0
# v should be a numpy array with values between 0.0 and 255.0
# hsv _ to _ rgb returns an array of uints between 0 and 255.
rgb = np . empty_like ( hsv )
rgb [ ... , 3 : ] = hsv [ ... , 3 : ]
h , s , v = hsv [ ... , 0 ] , hsv [ ... , 1 ] , hsv [ ... , 2 ]
i = ( h * 6.0 ) . astype ( 'uint8' )
f = ( h * 6.0 ) - i
p = v * ( 1.0 - s )
q = v * ( 1.0 - s * f )
t = v * ( 1.0 - s * ( 1.0 - f ) )
i = i % 6
conditions = [ s == 0.0 , i == 1 , i == 2 , i == 3 , i == 4 , i == 5 ]
rgb [ ... , 0 ] = np . select ( conditions , [ v , q , p , p , t , v ] , default = v )
rgb [ ... , 1 ] = np . select ( conditions , [ v , v , v , q , p , p ] , default = t )
rgb [ ... , 2 ] = np . select ( conditions , [ v , p , t , v , v , q ] , default = p )
return rgb . astype ( 'uint8' )


signature:
def adjust_hue ( im , hout = 0.66 , is_offset = True , is_clip = True , is_random = False ) :
    """Adjust hue of an RGB image .
 This is a convenience method that converts an RGB image to float representation , converts it to HSV , add an offset to the hue channel , converts back to RGB and then back to the original data type .
 For TF , see ` tf . image . adjust _ hue < https : / / www . tensorflow . org / api _ docs / python / tf / image / adjust _ hue > ` _ _ . and ` tf . image . random _ hue < https : / / www . tensorflow . org / api _ docs / python / tf / image / random _ hue > ` _ _ .
 Parameters
 im : numpy . array
 An image with values between 0 and 255.
 hout : float
 The scale value for adjusting hue .
 - If is _ offset is False , set all hue values to this value . 0 is red ; 0.33 is green ; 0.66 is blue .
 - If is _ offset is True , add this value as the offset to the hue channel .
 is _ offset : boolean
 Whether ` hout ` is added on HSV as offset or not . Default is True .
 is _ clip : boolean
 If HSV value smaller than 0 , set to 0 . Default is True .
 is _ random : boolean
 If True , randomly change hue . Default is False .
 Returns
 numpy . array
 A processed image .
 Examples
 Random , add a random value between - 0.2 and 0.2 as the offset to every hue values .
 > > > im _ hue = tl . prepro . adjust _ hue ( image , hout = 0.2 , is _ offset = True , is _ random = False )
 Non - random , make all hue to green .
 > > > im _ green = tl . prepro . adjust _ hue ( image , hout = 0.66 , is _ offset = False , is _ random = False )
 References
 - ` tf . image . random _ hue < https : / / www . tensorflow . org / api _ docs / python / tf / image / random _ hue > ` _ _ .
 - ` tf . image . adjust _ hue < https : / / www . tensorflow . org / api _ docs / python / tf / image / adjust _ hue > ` _ _ .
 - ` StackOverflow : Changing image hue with python PIL < https : / / stackoverflow . com / questions / 7274221 / changing - image - hue - with - python - pil > ` _ _ ."""

implementation:
hsv = rgb_to_hsv ( im )
if is_random :
    hout = np . random . uniform ( - hout , hout )
if is_offset :
    hsv [ ... , 0 ] += hout
else :
    hsv [ ... , 0 ] = hout
if is_clip :
    hsv [ ... , 0 ] = np . clip ( hsv [ ... , 0 ] , 0 , np . inf )
# Hao : can remove green dots
rgb = hsv_to_rgb ( hsv )
return rgb


signature:
def imresize ( x , size = None , interp = 'bicubic' , mode = None ) :
    """Resize an image by given output size and method .
 Warning , this function will rescale the value to [ 0 , 255 ] .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 size : list of 2 int or None
 For height and width .
 interp : str
 Interpolation method for re - sizing ( ` nearest ` , ` lanczos ` , ` bilinear ` , ` bicubic ` ( default ) or ` cubic ` ) .
 mode : str
 The PIL image mode ( ` P ` , ` L ` , etc . ) to convert image before resizing .
 Returns
 numpy . array
 A processed image .
 References
 - ` scipy . misc . imresize < https : / / docs . scipy . org / doc / scipy / reference / generated / scipy . misc . imresize . html > ` _ _"""

implementation:
if size is None :
    size = [ 100 , 100 ]
if x . shape [ - 1 ] == 1 : # greyscale
    x = scipy . misc . imresize ( x [ : , : , 0 ] , size , interp = interp , mode = mode )
    return x [ : , : , np . newaxis ]
else : # rgb , bgr , rgba
    return scipy . misc . imresize ( x , size , interp = interp , mode = mode )


signature:
def pixel_value_scale ( im , val = 0.9 , clip = None , is_random = False ) :
    """Scales each value in the pixels of the image .
 Parameters
 im : numpy . array
 An image .
 val : float
 The scale value for changing pixel value .
 - If is _ random = False , multiply this value with all pixels .
 - If is _ random = True , multiply a value between [ 1 - val , 1 + val ] with all pixels .
 clip : tuple of 2 numbers
 The minimum and maximum value .
 is _ random : boolean
 If True , see ` ` val ` ` .
 Returns
 numpy . array
 A processed image .
 Examples
 Random
 > > > im = pixel _ value _ scale ( im , 0.1 , [ 0 , 255 ] , is _ random = True )
 Non - random
 > > > im = pixel _ value _ scale ( im , 0.9 , [ 0 , 255 ] , is _ random = False )"""

implementation:
clip = clip if clip is not None else ( - np . inf , np . inf )
if is_random :
    scale = 1 + np . random . uniform ( - val , val )
    im = im * scale
else :
    im = im * val
if len ( clip ) == 2 :
    im = np . clip ( im , clip [ 0 ] , clip [ 1 ] )
else :
    raise Exception ( "clip : tuple of 2 numbers" )
return im


signature:
def samplewise_norm ( x , rescale = None , samplewise_center = False , samplewise_std_normalization = False , channel_index = 2 , epsilon = 1e-7 ) :
    """Normalize an image by rescale , samplewise centering and samplewise centering in order .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 rescale : float
 Rescaling factor . If None or 0 , no rescaling is applied , otherwise we multiply the data by the value provided ( before applying any other transformation )
 samplewise _ center : boolean
 If True , set each sample mean to 0.
 samplewise _ std _ normalization : boolean
 If True , divide each input by its std .
 epsilon : float
 A small position value for dividing standard deviation .
 Returns
 numpy . array
 A processed image .
 Examples
 > > > x = samplewise _ norm ( x , samplewise _ center = True , samplewise _ std _ normalization = True )
 > > > print ( x . shape , np . mean ( x ) , np . std ( x ) )
 (160 , 176 , 1 ) , 0.0 , 1.0
 Notes
 When samplewise _ center and samplewise _ std _ normalization are True .
 - For greyscale image , every pixels are subtracted and divided by the mean and std of whole image .
 - For RGB image , every pixels are subtracted and divided by the mean and std of this pixel i . e . the mean and std of a pixel is 0 and 1."""

implementation:
if rescale :
    x *= rescale
if x . shape [ channel_index ] == 1 : # greyscale
    if samplewise_center :
        x = x - np . mean ( x )
    if samplewise_std_normalization :
        x = x / np . std ( x )
    return x
elif x . shape [ channel_index ] == 3 : # rgb
    if samplewise_center :
        x = x - np . mean ( x , axis = channel_index , keepdims = True )
    if samplewise_std_normalization :
        x = x / ( np . std ( x , axis = channel_index , keepdims = True ) + epsilon )
    return x
else :
    raise Exception ( "Unsupported channels %d" % x . shape [ channel_index ] )


signature:
def featurewise_norm ( x , mean = None , std = None , epsilon = 1e-7 ) :
    """Normalize every pixels by the same given mean and std , which are usually
 compute from all examples .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 mean : float
 Value for subtraction .
 std : float
 Value for division .
 epsilon : float
 A small position value for dividing standard deviation .
 Returns
 numpy . array
 A processed image ."""

implementation:
if mean :
    x = x - mean
if std :
    x = x / ( std + epsilon )
return x


signature:
def get_zca_whitening_principal_components_img ( X ) :
    """Return the ZCA whitening principal components matrix .
 Parameters
 x : numpy . array
 Batch of images with dimension of [ n _ example , row , col , channel ] ( default ) .
 Returns
 numpy . array
 A processed image ."""

implementation:
flatX = np . reshape ( X , ( X . shape [ 0 ] , X . shape [ 1 ] * X . shape [ 2 ] * X . shape [ 3 ] ) )
tl . logging . info ( "zca : computing sigma .." )
sigma = np . dot ( flatX . T , flatX ) / flatX . shape [ 0 ]
tl . logging . info ( "zca : computing U, S and V .." )
U , S , _ = linalg . svd ( sigma )
# USV
tl . logging . info ( "zca : computing principal components .." )
principal_components = np . dot ( np . dot ( U , np . diag ( 1. / np . sqrt ( S + 10e-7 ) ) ) , U . T )
return principal_components


signature:
def zca_whitening ( x , principal_components ) :
    """Apply ZCA whitening on an image by given principal components matrix .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 principal _ components : matrix
 Matrix from ` ` get _ zca _ whitening _ principal _ components _ img ` ` .
 Returns
 numpy . array
 A processed image ."""

implementation:
flatx = np . reshape ( x , ( x . size ) )
# tl . logging . info ( principal _ components . shape , x . shape ) # ( ( 28160 , 28160 ) , ( 160 , 176 , 1 ) )
# flatx = np . reshape ( x , ( x . shape ) )
# flatx = np . reshape ( x , ( x . shape [ 0 ] , ) )
# tl . logging . info ( flatx . shape ) # ( 160 , 176 , 1)
whitex = np . dot ( flatx , principal_components )
x = np . reshape ( whitex , ( x . shape [ 0 ] , x . shape [ 1 ] , x . shape [ 2 ] ) )
return x


signature:
def channel_shift ( x , intensity , is_random = False , channel_index = 2 ) :
    """Shift the channels of an image , randomly or non - randomly , see ` numpy . rollaxis < https : / / docs . scipy . org / doc / numpy / reference / generated / numpy . rollaxis . html > ` _ _ .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] ( default ) .
 intensity : float
 Intensity of shifting .
 is _ random : boolean
 If True , randomly shift . Default is False .
 channel _ index : int
 Index of channel . Default is 2.
 Returns
 numpy . array
 A processed image ."""

implementation:
if is_random :
    factor = np . random . uniform ( - intensity , intensity )
else :
    factor = intensity
x = np . rollaxis ( x , channel_index , 0 )
min_x , max_x = np . min ( x ) , np . max ( x )
channel_images = [ np . clip ( x_channel + factor , min_x , max_x ) for x_channel in x ]
x = np . stack ( channel_images , axis = 0 )
x = np . rollaxis ( x , 0 , channel_index + 1 )
return x


signature:
def channel_shift_multi ( x , intensity , is_random = False , channel_index = 2 ) :
    """Shift the channels of images with the same arguments , randomly or non - randomly , see ` numpy . rollaxis < https : / / docs . scipy . org / doc / numpy / reference / generated / numpy . rollaxis . html > ` _ _ .
 Usually be used for image segmentation which x = [ X , Y ] , X and Y should be matched .
 Parameters
 x : list of numpy . array
 List of images with dimension of [ n _ images , row , col , channel ] ( default ) .
 others : args
 See ` ` tl . prepro . channel _ shift ` ` .
 Returns
 numpy . array
 A list of processed images ."""

implementation:
if is_random :
    factor = np . random . uniform ( - intensity , intensity )
else :
    factor = intensity
results = [ ]
for data in x :
    data = np . rollaxis ( data , channel_index , 0 )
    min_x , max_x = np . min ( data ) , np . max ( data )
    channel_images = [ np . clip ( x_channel + factor , min_x , max_x ) for x_channel in x ]
    data = np . stack ( channel_images , axis = 0 )
    data = np . rollaxis ( x , 0 , channel_index + 1 )
    results . append ( data )
return np . asarray ( results )


signature:
def drop ( x , keep = 0.5 ) :
    """Randomly set some pixels to zero by a given keeping probability .
 Parameters
 x : numpy . array
 An image with dimension of [ row , col , channel ] or [ row , col ] .
 keep : float
 The keeping probability ( 0 , 1 ) , the lower more values will be set to zero .
 Returns
 numpy . array
 A processed image ."""

implementation:
if len ( x . shape ) == 3 :
    if x . shape [ - 1 ] == 3 : # color
        img_size = x . shape
        mask = np . random . binomial ( n = 1 , p = keep , size = x . shape [ : - 1 ] )
        for i in range ( 3 ) :
            x [ : , : , i ] = np . multiply ( x [ : , : , i ] , mask )
    elif x . shape [ - 1 ] == 1 : # greyscale image
        img_size = x . shape
        x = np . multiply ( x , np . random . binomial ( n = 1 , p = keep , size = img_size ) )
    else :
        raise Exception ( "Unsupported shape {}" . format ( x . shape ) )
elif len ( x . shape ) == 2 or 1 : # greyscale matrix ( image ) or vector
    img_size = x . shape
    x = np . multiply ( x , np . random . binomial ( n = 1 , p = keep , size = img_size ) )
else :
    raise Exception ( "Unsupported shape {}" . format ( x . shape ) )
return x


signature:
def array_to_img ( x , dim_ordering = ( 0 , 1 , 2 ) , scale = True ) :
    """Converts a numpy array to PIL image object ( uint8 format ) .
 Parameters
 x : numpy . array
 An image with dimension of 3 and channels of 1 or 3.
 dim _ ordering : tuple of 3 int
 Index of row , col and channel , default ( 0 , 1 , 2 ) , for theano ( 1 , 2 , 0 ) .
 scale : boolean
 If True , converts image to [ 0 , 255 ] from any range of value like [ - 1 , 2 ] . Default is True .
 Returns
 PIL . image
 An image .
 References
 ` PIL Image . fromarray < http : / / pillow . readthedocs . io / en / 3.1 . x / reference / Image . html ? highlight = fromarray > ` _ _"""

implementation:
# if dim _ ordering = = ' default ' :
# dim _ ordering = K . image _ dim _ ordering ( )
# if dim _ ordering = = ' th ' : # theano
# x = x . transpose ( 1 , 2 , 0)
x = x . transpose ( dim_ordering )
if scale :
    x += max ( - np . min ( x ) , 0 )
    x_max = np . max ( x )
    if x_max != 0 : # tl . logging . info ( x _ max )
    # x / = x _ max
        x = x / x_max
    x *= 255
if x . shape [ 2 ] == 3 : # RGB
    return PIL . Image . fromarray ( x . astype ( 'uint8' ) , 'RGB' )
elif x . shape [ 2 ] == 1 : # grayscale
    return PIL . Image . fromarray ( x [ : , : , 0 ] . astype ( 'uint8' ) , 'L' )
else :
    raise Exception ( 'Unsupported channel number: ' , x . shape [ 2 ] )