Disk image usage

Modules demonstrating how to use a disk image with PyIPSDK. More...

Modules demonstrating how to use a disk image with PyIPSDK.

When to use disk images

The image size can be very large in some applications. Processing such images will create several images with the same memory size, or even bigger. All of these data may not fit in the memory.

In this case, IPSDK offers the possibility to use disk images instead of memory images. Disk images are not allocated in the computer's RAM but a file is created to store the data on a drive.

It is possible to retrieve or change the path where the disk images are created by IPSDK with the functions PyIPSDK.getAllocatedDiskImagePath() and PyIPSDK.setAllocatedDiskImagePath("/new/path"):

    print("Default disk image directory :", PyIPSDK.getAllocatedDiskImagePath())
    newDir = os.path.expanduser("~") # Change the directory to $HOME
    PyIPSDK.setAllocatedDiskImagePath(newDir)
    print("New disk image directory :", PyIPSDK.getAllocatedDiskImagePath())

How to use disk images

By definition, a disk image is not loaded but only open. Instead of using PyIPSDK.loadTiffImageFile() or PyIPSDK.loadRawImageFile(), which load the data from the file to the memory, the functions PyIPSDK.openTiffImageFile() or PyIPSDK.openRawImageFile() must be called:

    # Uncomment to open a RAW file
    # geometry = PyIPSDK.geometry2d(PyIPSDK.eIBT_UInt8, 510, 509)
    # im = PyIPSDK.openRawImageFile(os.path.join(imagesSamplePath, "Lena_510x509_UInt8.raw"), geometry, 0)

    # Open a TIFF file
    im = PyIPSDK.openTiffImageFile(os.path.join(imagesSamplePath, "porosity_125x97x47_UInt16.tif"))

The image can then be processed as a classical image :

    print("Processing a disk image...")

    out = util.copyImg(im)

It is possible to check if the output image is a disk image or not :

    # Test if the image is a disk image
    print("Is disk image", out.isDiskImage())

It is also possible to modify a single value directly in the file. In the following example, we set the intensity of the very first pixel (x = y = z = c = t = 0) to 255 :

    # Change the value of the first pixel
    print("Set the intensity of the first pixel to 255")
    out.writePixel(255, 0, 0, 0, 0, 0)

It can be usefull to extract a slice, a channel or a frame from the disk image, or at least a subsample of this slice. It is required for instance for vizualization purpose. In that case, the extracted data is stored as a classical memory image, since it is supposed to contain much less data and therefore fit in memory. The slice coordinate (z, c, t), the size of the new memory image, its offset and the stride (i.e. the step between 2 extracted pixels) must be provided:

    # Load a sub-set of a slice in an IPSDK memory image instance
    # The image can be used as any other IPSDK image
    outMem = out.loadPlan(0, 0, 0, outSizeX, outSizeY, offsetX, offsetY, strideX, strideY)

Because the result is a classical IPSDK memory image, its numpy array is accessible and it can be displayed or processed:

    # Print the first values
    print("First pixels in the extracted plan :", outMem.array[0, :4])

    # Display the extracted sub-plan
    ui.displayImg(outMem, "Plan subset")

Finally, keep in mind that the file is removed when the program exits the image scope, such as the end of the function or terminating the program. This meas that the image still need to be saved in a RAW or TIFF file.

To manually remove the disk file, simply set the variable to none: out = None.