birl.utilities.data_io module

Useful function for managing Input/Output

Copyright (C) 2017-2019 Jiri Borovec <jiri.borovec@fel.cvut.cz>

birl.utilities.data_io._gene_out_path(path_file, file_ext, path_out_dir=None)[source]

generate new path with the same file name just changed extension (and folder)

Parameters

  • path_file (str) – path of source file (image)

  • file_ext (str) – file extension of desired file

  • path_out_dir (str) – destination folder, if NOne use the input dir

Return str

desired file

birl.utilities.data_io.convert_image_from_mhd(path_image, path_out_dir=None, img_ext='.png', scaling=None)[source]

convert standard image to MHD format

See also

https://www.programcreek.com/python/example/96382/SimpleITK.WriteImage

Parameters

  • path_image (str) – path to the input image

  • path_out_dir (str) – path to output directory, if None use the input dir

  • img_ext (str) – image extension like PNG or JPEG

  • scaling (float|None) – image down-scaling, resulting image will be larger by this factor

Return str

path to exported image

>>> path_img = os.path.join(update_path('data-images'), 'images',
...                         'artificial_reference.jpg')
>>> path_img = convert_image_to_mhd(path_img, scaling=1.5)
>>> convert_image_from_mhd(path_img, scaling=1.5)  
'...artificial_reference.png'
birl.utilities.data_io.convert_image_from_nifti(path_image, path_out_dir=None)[source]

converting Nifti to standard image

Parameters

  • path_image (str) – path to input image

  • path_out_dir (str) – destination directory, if Nne use the same folder

Return str

path to new image

birl.utilities.data_io.convert_image_to_mhd(path_image, path_out_dir=None, to_gray=True, overwrite=True, scaling=None)[source]

converting standard image to MHD (Nifty format)

See also

https://stackoverflow.com/questions/37290631

Parameters

  • path_image (str) – path to the input image

  • path_out_dir (str) – path to output directory, if None use the input dir

  • overwrite (bool) – allow overwrite existing image

  • scaling (float|None) – image up-scaling resulting image will be smaller by this factor

Return str

path to exported image

>>> path_img = os.path.join(update_path('data-images'), 'images',
...                         'artificial_moving-affine.jpg')
>>> convert_image_to_mhd(path_img, scaling=2)  
'...artificial_moving-affine.mhd'
birl.utilities.data_io.convert_image_to_nifti(path_image, path_out_dir=None)[source]

converting normal image to Nifty Image

Parameters

  • path_image (str) – input image

  • path_out_dir (str) – path to output folder

Return str

resulted image

>>> path_img = os.path.join(update_path('data-images'), 'images',
...                         'artificial_moving-affine.jpg')
>>> path_img2 = convert_image_to_nifti(path_img, '.')
>>> path_img2  
'...artificial_moving-affine.nii'
>>> os.path.isfile(path_img2)
True
>>> path_img3 = convert_image_from_nifti(path_img2)
>>> os.path.isfile(path_img3)
True
>>> list(map(os.remove, [path_img2, path_img3]))  
[...]
birl.utilities.data_io.convert_image_to_nifti_gray(path_image, path_out_dir=None)[source]

converting normal image to Nifty Image

Parameters

  • path_image (str) – input image

  • path_out_dir (str) – path to output folder

Return str

resulted image

>>> path_img = './sample-image.png'
>>> save_image(path_img, np.zeros((100, 200, 3)))
>>> path_img2 = convert_image_to_nifti_gray(path_img)
>>> os.path.isfile(path_img2)
True
>>> path_img3 = convert_image_from_nifti(path_img2, '.')
>>> os.path.isfile(path_img3)
True
>>> list(map(os.remove, [path_img, path_img2, path_img3]))  
[...]
birl.utilities.data_io.convert_ndarray2image(image)[source]

convert ndarray to PIL image if it not already

Parameters

image (ndarray) – input image

Return Image

output image

>>> img = np.random.random((50, 50, 3))
>>> image = convert_ndarray2image(img)
>>> isinstance(image, Image.Image)
True
birl.utilities.data_io.create_folder(path_folder, ok_existing=True)[source]

create a folder if it not exists

Parameters

  • path_folder (str) – path to creating folder

  • ok_existing (bool) – suppress warning for missing

Return str|None

path to created folder

>>> p_dir = create_folder('./sample-folder', ok_existing=True)
>>> create_folder('./sample-folder', ok_existing=False)
False
>>> os.rmdir(p_dir)
birl.utilities.data_io.image_resize(img, scale=1.0, v_range=255, dtype=<class 'int'>)[source]

rescale image with other optional formating

Parameters

  • img (ndarray) – input image

  • scale (float) – the new image size is im_size * scale

  • v_range (int|float) – desired output image range 1. or 255

  • dtype – output image type

Return ndarray

image

>>> np.random.seed(0)
>>> img = image_resize(np.random.random((250, 300, 3)), scale=2, v_range=255)
>>> np.array(img.shape, dtype=int)
array([500, 600,   3])
>>> img.max()
255
birl.utilities.data_io.image_sizes(path_image, decimal=1)[source]

get image size (without loading image raster)

Parameters

  • path_image (str) – path to the image

  • decimal (int) – rounding digits

Return tuple(tuple(int,int),float)

image size (height, width) and diagonal

>>> img = np.random.random((50, 75, 3))
>>> save_image('./test_image.jpg', img)
>>> image_sizes('./test_image.jpg', decimal=0)
((50, 75), 90.0)
>>> os.remove('./test_image.jpg')
birl.utilities.data_io.io_image_decorate(func)[source]

costume decorator to suppers debug messages from the PIL function to suppress PIl debug logging - DEBUG:PIL.PngImagePlugin:STREAM b’IHDR’ 16 13

Parameters

func – decorated function

Return func

output of the decor. function

birl.utilities.data_io.load_config_args(path_config, comment='#')[source]

load config arguments from file with dropping comments

Parameters

  • path_config (str) – configuration file

  • comment (str) – character defining comments

Return str

concat arguments

>>> p_conf = './sample-arg-config.txt'
>>> with open(p_conf, 'w') as fp:
...     fp.writelines(os.linesep.join(['# comment', '', ' -a 1  ', ' --b c#d']))
>>> load_config_args(p_conf)
'-a 1 --b c'
>>> os.remove(p_conf)
birl.utilities.data_io.load_config_yaml(path_config)[source]

loading the

Parameters

path_config (str) –

Return dict

>>> p_conf = './testing-congif.yaml'
>>> save_config_yaml(p_conf, {'a': 2})
>>> load_config_yaml(p_conf)
{'a': 2}
>>> os.remove(p_conf)
birl.utilities.data_io.load_image(path_image, force_rgb=True)[source]

load the image in value range (0, 1)

Parameters

  • path_image (str) – path to the image

  • force_rgb (bool) – convert RGB image

Return ndarray

np.array<height, width, ch>

>>> img = np.random.random((50, 50))
>>> save_image('./test_image.jpg', img)
>>> img2 = load_image('./test_image.jpg')
>>> img2.max() <= 1.
True
>>> os.remove('./test_image.jpg')
birl.utilities.data_io.load_landmarks(path_file)[source]

load landmarks in csv and txt format

Parameters

path_file (str) – path to the input file

Return ndarray

np.array<np_points, dim> of landmarks points

>>> points = np.array([[1, 2], [3, 4], [5, 6]])
>>> save_landmarks('./sample_landmarks.csv', points)
>>> pts1 = load_landmarks('./sample_landmarks.csv')
>>> pts2 = load_landmarks('./sample_landmarks.pts')
>>> np.array_equal(pts1, pts2)
True
>>> os.remove('./sample_landmarks.csv')
>>> os.remove('./sample_landmarks.pts')

>>> # Wrong loading
>>> load_landmarks('./sample_landmarks.file')
>>> open('./sample_landmarks.file', 'w').close()
>>> load_landmarks('./sample_landmarks.file')
>>> os.remove('./sample_landmarks.file')
birl.utilities.data_io.load_landmarks_csv(path_file)[source]

load file with landmarks in cdv format

Parameters

path_file (str) – path to the input file

Return ndarray

np.array<np_points, dim> of landmarks points

>>> points = np.array([[1, 2], [3, 4], [5, 6]])
>>> p_lnds = save_landmarks_csv('./sample_landmarks', points)
>>> p_lnds
'./sample_landmarks.csv'
>>> pts = load_landmarks_csv(p_lnds)
>>> pts  
array([[1, 2],
       [3, 4],
       [5, 6]]...)
>>> os.remove('./sample_landmarks.csv')
birl.utilities.data_io.load_landmarks_pts(path_file)[source]

load file with landmarks in txt format

Parameters

path_file (str) – path to the input file

Return ndarray

np.array<np_points, dim> of landmarks points

>>> points = np.array([[1, 2], [3, 4], [5, 6]])
>>> p_lnds = save_landmarks_pts('./sample_landmarks.csv', points)
>>> p_lnds
'./sample_landmarks.pts'
>>> pts = load_landmarks_pts(p_lnds)
>>> pts  
array([[ 1.,  2.],
       [ 3.,  4.],
       [ 5.,  6.]])
>>> os.remove('./sample_landmarks.pts')

>>> # Empty landmarks
>>> open('./sample_landmarks.pts', 'w').close()
>>> load_landmarks_pts('./sample_landmarks.pts').size
0
>>> os.remove('./sample_landmarks.pts')
birl.utilities.data_io.save_config_yaml(path_config, config)[source]

exporting configuration as YAML file

Parameters

  • path_config (str) –

  • config (dict) –

birl.utilities.data_io.save_image(path_image, image)[source]

save the image into given path

Parameters

  • path_image (str) – path to the image

  • image – np.array<height, width, ch>

>>> # Wrong path
>>> save_image('./missing-path/any-image.png', np.zeros((10, 20)))
False
birl.utilities.data_io.save_landmarks(path_file, landmarks)[source]

save landmarks into a specific file

both used formats csv/pts is using the same coordinate frame, the origin (0, 0) is located in top left corner of the image

Parameters

  • path_file (str) – path to the output file

  • landmarks – np.array<np_points, dim>

birl.utilities.data_io.save_landmarks_csv(path_file, landmarks)[source]

save landmarks into a csv file

we are using simple format:

,X,Y
0,point1-x,point1-y
1,point2-x,point2-y
Parameters

  • path_file (str) – path to the output file

  • landmarks – np.array<np_points, dim>

Return str

file path

birl.utilities.data_io.save_landmarks_pts(path_file, landmarks)[source]

save landmarks into a txt file

we are using VTK pointdata legacy format, ITK compatible:

<index, point>
<number of points>
point1-x point1-y [point1-z]
point2-x point2-y [point2-z]

See also

https://simpleelastix.readthedocs.io/PointBasedRegistration.html

Parameters

  • path_file (str) – path to the output file

  • landmarks – np.array<np_points, dim>

Return str

file path

birl.utilities.data_io.update_path(a_path, pre_path=None, lim_depth=5, absolute=True)[source]

bubble in the folder tree up until it found desired file otherwise return original one

Parameters

  • a_path (str) – original path

  • base_path (str|None) – special case when you want to add something before

  • lim_depth (int) – max depth of going up in the folder tree

  • absolute (bool) – format as absolute path

Return str

updated path if it exists otherwise the original one

>>> os.path.exists(update_path('./birl', absolute=False))
True
>>> os.path.exists(update_path('/', absolute=False))
True
>>> os.path.exists(update_path('~', absolute=False))
True
birl.utilities.data_io.LANDMARK_COORDS = ['X', 'Y'][source]

landmarks coordinates, loading from CSV file