file Package

file_utils Module

pymicro.file.file_utils.read_image_sequence(data_dir, prefix, num_images, start_index=0, image_format='png', zero_padding=0, crop=None, verbose=False)

Read a series of images into a list of numpy arrays.

  • data_dir (str) – directory where the image files are located.

  • prefix (str) – a string to construct the image file names.

  • num_images (int) – the number of images to read.

  • start_index (int) – the index to start loading the images (0 by default).

  • image_format (str) – can be tif or png (png by default).

  • zero_padding (int) – number of zero to use in zero padding (0 by default).

  • crop (list) – bounds to crop the images (None by default)

  • verbose (bool) – activate verbose mode (False by default).


the list of the images read from the disk.


Unpack an ascii header.

Form a string with the read binary data and then split it into string tokens which are put in a dictionnary.


header (str) – the ascii header to unpack.


a dictionnary with the (key, value) fields contained in the header.

pymicro.file.file_utils.edf_info(file_name, header_size=None, verbose=False)

Read and return informations contained in the header of a .edf file.

Edf files always start with a header (of variable length) containing information about the file such as acquisition conditions, image dimensions… This function reads a certain amount of bytes of a given file as ascii data and unpack it. If not specified, the header size is determined automatically by substracting the data size (read as ascii at the begining of the file) to the total file size.

  • file_name (str) – the name of the edf file to read.

  • header_size (int) – number of bytes to read as a multiple of 512 (None by default).

  • verbose (bool) – flag to activate verbose mode.


a dictionary containing the file information.

pymicro.file.file_utils.edf_read(file_name, verbose=False)

Read an edf file.

edf stands for ESRF data file. It has a variable header size which is a multiple of 512 bytes and contains the image meta in ASCII format (eg. image size, data type, motor positions).

The ascii header is parsed automatically by edf_info to retreive the image size and data type. Depending on the information enclosed in the header, this function may return a 1d, 2d or 3d array.

>>> im = edf_read('radio.edf')
>>> im.shape
(2048, 2048)
  • file_name (str) – the name of the edf file to read.

  • verbose (bool) – flag to activate verbose mode.


a numpy array containing the data

pymicro.file.file_utils.edf_write(data, file_name, header_size=1024)

Write a binary edf file with the appropriate header.

This function write a (x,y,z) 3D dataset to the disk. The file is written as a Z-stack. It means that the first nx*ny bytes represent the first slice and so on…

  • data (ndarray) – the data array to write to the file.

  • file_name (str) – the file name to use.

  • header_size (int) – the size of te header (a multiple of 512).


Read the given info file and returns a dictionary containing the data size and type.


The first line of the file must begin by ! PyHST or directly by NUM_X. Also note that if the data type is not specified, it will not be present in the dictionary.


info_file (str) – path to the ascii file to read.


a dictionary with the values for x_dim, y_dim, z_dim and data_type if needed.

pymicro.file.file_utils.HST_read(scan_name, zrange=None, data_type=<Mock name='mock.uint8' id='140580273163472'>, verbose=False, header_size=0, autoparse_filename=False, dims=None, mmap=False, pack_binary=False)

Read a volume file stored as a concatenated stack of binary images.

The volume size must be specified by dims=(nx, ny, nz) unless an associated .info file is present in the same location to determine the volume size. The data type is unsigned short (8 bits) by default but can be set to any numpy type (32 bits float for example).

The autoparse_filename can be activated to retreive image type and size:

HST_read(myvol_100x200x50_uint16.raw, autoparse_filename=True)

will read the 3d image as unsigned 16 bits with size 100 x 200 x 50.


If you use this function to read a .edf file written by matlab in +y+x+z convention (column major order), you may want to use: np.swapaxes(HST_read(‘file.edf’, …), 0, 1)

  • scan_name (str) – path to the binary file to read.

  • zrange – range of slices to use.

  • data_type – numpy data type to use.

  • verbose (bool) – flag to activate verbose mode.

  • header_size (int) – number of bytes to skeep before reading the payload.

  • autoparse_filename (bool) – flag to parse the file name to retreive the dims and data_type automatically.

  • dims (tuple) – a tuple containing the array dimensions.

  • mmap (bool) – activate the memory mapping mode.

  • pack_binary (bool) – this flag should be true when reading a file written with the binary packing mode.

pymicro.file.file_utils.rawmar_read(image_name, size, verbose=False)

Read a square 2D image plate MAR image.

These binary images are typically obtained from the marcvt utility.


This method assume Big endian byte order.

pymicro.file.file_utils.HST_write(data, file_name, mode='w', verbose=True, pack_binary=False)

Write data as a raw binary file.

This function write a (x,y,z) 3D dataset to the disk. The actual data type is used, you can convert your data array on the fly using data.astype if you want to change the type. The file is written as a Z-stack. It means that the first nx*ny bytes written represent the first slice and so on… For binary data files (stored in memory as integer or bool data type), binary packing mode can be activated which stores 8 values on each byte (saving 7/8 of the disk space).

A .info file containing the volume size and data type is also written.

  • data – the 3d array to write to the disk in [x, y, z] form.

  • file_name (str) – the name of the file to write, including file extension.

  • mode (char) – file write mode, change to ‘a’ to append to a file.

  • verbose (bool) – flag to activate verbose mode.

  • pack_binary (bool) – flag to activate binary packing.

pymicro.file.file_utils.recad_vol(vol_filename, min, max, verbose=False)

Recad a 32 bit vol file into 8 bit raw file.

This function reads a 3D volume file into a numpy float32 array and applies the recad function with the [min, max] range. The result is saved into a .raw file with the same name as the input file.

In verbose mode, a piture to compare mid slices in the two volumes and another one to compare the histograms are saved.


To read the vol file, the presence of a .info file is assumed, see HST_read.


vol_filename: the path to the binary vol file.

min: value to use as the minimum (will be 0 in the casted array).

max: value to use as the maximum (will be 255 in the casted array).

verbose: activate verbose mode (False by default).

pymicro.file.file_utils.Vtk_write(data, fname)

Write a data array into old style (V3.0) VTK format.

An ascii header is written to which the binary data is appended.


The header assumes uint8 data type.