Tutorial: Image Reader¶

Overview¶

The Zinc library uses streams to read in data from disk or memory. The image reader application shows how to read in an image from disk using the Zinc library stream API. The same process is followed when reading an image in from memory, the only difference is the stream resource type that is used.

The souce code used in this tutorial is available from the physiome project svn server.

The Code¶

Here is the code for reading in an image from disk:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

def main():
    '''
    The entry point for the application, handle application arguments.
    '''
    # Create the context
    context = Context("image")
    
    # Name of the file we intend to read in.
    image_name = 'drawing.png'
    
    # Get a handle to the root region
    default_region = context.getDefaultRegion()
    
    # The field module allows us to create a field image to 
    # store the image data into.
    field_module = default_region.getFieldmodule()
    
    # Create an image field, we don't specify the domain here for this
    # field even though it is a source field.  A temporary xi source field
    # is created for us.
    image_field = field_module.createFieldImage()
    image_field.setName('texture')
    
    # Create a stream information object that we can use to read the 
    # image file from the disk
    stream_information = image_field.createStreaminformationImage()
    # Set the format for the image we want to read
    stream_information.setFileFormat(stream_information.FILE_FORMAT_PNG)
    # We are reading in a file from the local disk so our resource is a file.
    stream_information.createStreamresourceFile(image_name)
    
    # Actually read in the image file into the image field.
    ret = image_field.read(stream_information)
    if ret == 1: # CMISS_OK has  the literal value 1
        print('Image successfully read into image field.')
    else:
        print('Error: failed to read image into image field.')
        

Line 6 creates the Zinc context we must create one of these to get any other objects from this context.

To create an image field we first must get the default region from the context (Line 12) and then we can get the field module for that region (Line 16). From the field module we can create any fields required, in our case we want an image field.

An image field is created over a domain but if we don’t supply one the create image field method will construct one for us. The constructed domain will be over xi space [0-1]x[0-1]x[0-1] irrespective of the dimensionality of the image data. It is possible to construct a domain better suited for our image data but we will leave this for a later tutorial.

Line 21 creates an image field and implicitly a domain for it. Line 22 sets the name of the image field to ‘texture’, naming a field can be useful if we wish to find it by name later.

To read the data into the image field we need to create a stream information object which will hold all the information required to read in the image. Line 26 creates the stream information object and line 28 sets the image file format to png.

It is not absolutely necessary to set the image file format as some guesswork will take place if it is not set, although reading of the image data will fail if the image file format can not be determined. Line 30 creates a file resource to read in the file from disk. Alternatively we could use a memory resource this type of resource is typically used when reading an image in from a compressed archive. The uncompressed image is held in memory which we can pass through directly.

All the information required to read the image is now in place and line 33 actually reads in the image data. We can check the result of the read by comparing the return value with CMISS_OK, which currently has the literal value of 1.

When we execute this application, if everything went well, we should see:

Image successfully read into image field.