Hello. I have an ML feature classifier for NIfTI images, but the caveat requires the images to be the same dimensions, and it would also be best if I could perform histogram equalization (So that all images have similar range of intensities)

I googled everywhere for a convenient way to do histogram equalization, and landed on CMTK since I prefer command line tools. I built from source and am now able to access the CMTK man pages for the various binaries. I see the 'warp' binary has the ability to do histogram equalization in the huge list of options, but there are no examples or even a basic usage string showing how to specify input and reference images...

Would it be too much trouble to ask for an example command that would reslice an input image and match histograms based on a reference image? Is it possible to do reslicing and histogram matching in one command? That would be fantastic.

Thanks,

Eli

Originally posted by Elijah Rockers:
OK I see now that the synopsis acts as a basic usage example. I'm not sure what the InitialXform argument should be. In fact I am most concerned with doing the histogram equalization, since I have other tools that I can perform the reslicing with if needed.

I am running the following command right now
It is taking a fantastically long time, and I have a feeling it is doing some spatial warping that I am not really interested in... any advice would be appreciated,

Thanks in advance.

warp does image registration, which is not what you want.

Take a look at the command line help for convertx and possibly imagemath

There are options to match histograms of a target image, but I think you will need to specify image dimensions explicitly for resampling.

As usual Torsten will know more.

Best,

Greg.

Hi Eli -

As Greg already mentioned, the "warp" tool is not what you want. It can do histogram equalization internally prior to aligning two images, but that's just for convenience and does not let you export the normalized image.

Either imagemath or convertx should do what you want. IIRC the command line switch in both cases is --match-histograms. The operation of convertx is perhaps a bit more intuitive, since it follows a conceptual pattern of "input, modify, output". The imagemath tool, on the other hand, allows you to apply almost arbitrary sequences of operations to an arbitrary number of images, but that flexibility comes with the price of using an image stack and applying operations to the top image(s) on the stack. If that sounds confusing, that's probably a good sign to stick with convertx for operations that both tools support.

You asked for a command line, and my best guess (sorry, it's been a long time) is that this should work:

convertx --match-histograms RefImage InputImage OutputImage

That should match the histogram of InputImage to that of RefImage and write the result to OutputImage.

If that doesn't work, try convertx --help and check whether my memory was correct on the syntax.

Now for reslicing - the tool you want for that is either convertx or reformatx.

The convertx tool is simpler but can only do downsampling by integer facters. The two options of interest are --downsample-select and --downsample average. Each takes either a single downsample factor, or a comma-separated list of three (one per image axis). The former will simply use the value of a single corresponding pixel from the input image, whereas the latter will average the input image pixels that make up each output pixel. Which one you want depends on your application. For label images, you'd definitely want the "select" option. For intensity images, you're likely better off using the "average" variant.

If you have to upsample one image, though, or if your downsampling factors aren't integers, then you'll likely need to use the reformatx tool. Its general use is like so:

reformatx --floating MovingImage --output OutImage FixedImage

This should reslice the pixels in MovingImage to the grid of FixedImage and write the result to OutputImage. The reason for the somewhat un-intuitive order of arguments is that after FixedImage, you can optionally provide a sequence of (optionally inverted) coordinate transformations that define the mapping from FixedImage to MovingImage coordinates. But it sounds like your images are pre-aligned, so I would ignore that.

Instead, a word of caution about "pre-aligned" images then - there is likely going to be a half-pixel shift between your images if you simply apply reformatx as per the instructions above. The reason for that is in the pixel model that CMTK uses internally - basically, a pixel is a grid point, but it does not have a spatial extent. So what you might think of as "pixel size" is really the distance between two adjacent pixels, but the pixels themselves have no size. (Why is that? Because otherwise pixels on the image borders would have different sizes from interior pixels, or extend outside the image, each of which is adding a lot of complication for no real benefit. But I digress.)

Anyway, the result of that pixel model is this - the extent of an image with n pixels of "size" (really, distance) d, is (n-1)*d, not n*d. So if you have twice as many pixels, the extent would be (2n-1)*d, which is *not* twice the size of the former image (that would be (2n-2)*d). As a result, the pixels in the two images will not align if you simply align the image origins. Instead, they will be shifted.

Anyway, long story short, if you need to upsample or your images have pixel counts that aren't multiples of each other along each axis, then the whole thing gets a little complicated.

Torsten, this is very excellent information, thank you. Histogram matching helped improve the results. I changed the ML algorithm to handle images of different sizes, so the reslicing issue became moot, but I sincerely appreciate your thorough explanation, very helpful. I will add CMTK to our institution's standard imaging toolkit.

- Eli

Happy to help :)