Annotations which stay solely in Bisque aren’t incredibly useful. One of the main reasons for marking up images is to be able to use those annotations for some other purpose, such as training classifiers, computing metrics and features. In this post, we show how to take the annotations from bisque via REST, and convert them into binary masks in matlab.

In general the concept is similar to other posts, but of course there are always some unique variables which must be taken into account.

We begin by looking at what our annotation looks like, here we can see a region created with a “polygon” type object. Additionally, we can see that its filename is 8974_01018.tif.

This process has 4 steps:

1. Obtain URI for filename
2. Use URI to obtain xml annotations
3. Parse XML to x,y coordinates
4. Convert x,y coordinates into binary mark

Step 1: Obtain URI for filename

We query the image resource of the dataset service, specifying the filename that we’re interested in getting annotations for. This looks like this:

We use the urlread function of matlab to perform the REST GET, but we need to make sure that we also supply a username and password and specify that we’ll be using basic http authentication.

Once the function returns, we have an xml block containing all of the files which have the associated filename. Here we assume that there is only one file which has that filename, otherwise you can add on additional constraints or cycle through them to find the one of interest. Additional information on how to do that is here.

We then use a regular expression to grab the URI located second in the returned xml. We use the second one, because the first URI is associated with the resource query. Afterwards we have a URI that looks like this:

Step 2: Use URI to obtain xml annotations

Super simple. Now that we have the URI, we append gojects to the end of it and hit the REST GET again to get an xml string containing the annotations:

Step 3: Parse XML to x,y coordinates

Once we have the xml string, we want to be able to parse it into an xml class so we can intelligently extract the data we’re looking for. We would like to use matlab’s xmlread, but it only accepts filenames or InputStreams. So to begin, we take our XML string and convert it to a java input stream:

Then, we can use that input stream as the input to the xml read function:

From there we proceed as “normal“, with the only small modification being that we use ‘poylgon’ as the element tag we’re interested instead of ‘region’. We also make vertex, x and y lowercase.

Step 4: Convert x,y coordinates into binary mark

Using very similar code, we create the binary mask. The main qualm about this is that we need to know the number of rows and columns in the original image in order to be able to make a mask the same size. If the files are all of a fixed size, there is no need to obtain the dimensions as they can be fixed, and we’re not using the original image in any other way.

From there we can display the mask and see that it is exactly the same mask that we created before

Also we can use the binary mask overlay post to display the outline which is indeed matching with our original annotation.

Wait….Can’t I just query the nrow and ncol values?

Though, lets say you don’t have the original image handy. Bisque should be able to provide meta data associated with the image, right? Yessss…..

We can use the image service to give us some information about the image by using GET on this address:

we get back a nice chunk of information about the image:

Inside we can see our image_num_x and image_num_y variables which contain our columns and rows, respectively. The question is then, how do we get this information out? Our normal xml parsing technique won’t work because the tag don’t have unique names, instead they have unique attributes. So, one way, is to iterate through all of the tags and stop when we get to a tag that we want. That is quite fine, but I was feeling a bit fancy and decided to step up my game. How do you ask? Using a compiled XPath 🙂

So to begin, we again get the xml using the urlread as before:

From there we need to load the xpath classes and setup a new xpath instance:

Once that is done, we simply compile two expressions, one for the x value and one for the y value, storing them into ncol and nrow, respectively: