Friday, 19 November 2010

Help

About NeuroPub

NeuroPub is a visualizer for statistical brain images (fMRI, VBM, etc) and other kind of images (atlases etc) that can be visualised as an overlay on top of the standard MNI brain. It keeps a list of all the images you have imported to the app, so you always have immediate access to your research. This makes it a great tool to bring to conferences and meetings. You can have your own library of statistical images that you always carry with you, so you don't miss a chance of demonstrating your latest results when meeting others in the neuroimaging field.

This help text describes version 1.2.

Starting the app for the first time

Both the iPhone and the iPad version have exactly the same features, but there are some minor differences. These which will be described below.

iPhone

When you start the app the first time on your iPhone, you will see an image list containing one file (example.nii.gz). If you tap on that image, you will get into the visualizer, which will visualise the example image as an overlay on the standard brain.

There are two buttons at the bottom of the image list: Reload and Help. The Help button brings you to this page. The Reload button will be further discussed under the section Controls and buttons.

iPad

When you start the app on your iPad, you will immediately get into the visualizer. If you start the app in landscape mode, you will also see the image list on the left side. Just like on the iPhone, this list will contain one file (example.nii.gz) and the image will get loaded if you tap on it. The image list will not be visible if you start the app in portrait mode, but you can then invoke the list by tapping on the Image List button that you find in the upper left corner.

The iPad version has only one button at the bottom of the image list (Reload). The Help button is located at the upper right corner.

Both iPhone & iPad


The example image (example.nii.gz) is included with the app and listed in the image list when you start the app for the first time. You cannot delete this image, but it will disappear from the image list as soon as you upload your own images.


Uploading images

Requirements

NeuroPub supports images in both .nii and .nii.gz (compressed) format. Images you upload must have the same resolution as the 2x2x2 mm^3 template that comes with SPM and FSL, and they need to be in float-format. Only images satisfying these demands will be listed in the image list. The coordinate transformation matrix must also be the same as the template. If you have FSL, you can use the fslhd command to check if your file fulfils the requirements. You should get these values:

data_type      FLOAT32

dim0           3


dim1           91
dim2           109
dim3           91
dim4           1

The data type must be FLOAT32 and the images must have the size 91x109x91. You cannot upload 4D files. Only 3D files are accepted.

pixdim1        2.0000000000
pixdim2        2.0000000000
pixdim3        2.0000000000

The voxel size must be 2x2x2 mm^3.

sto_xyz:1      -2.000000  0.000000  0.000000  90.000000
sto_xyz:2      0.000000  2.000000  0.000000  -126.000000
sto_xyz:3      0.000000  0.000000  2.000000  -72.000000
sto_xyz:4      0.000000  0.000000  0.000000  1.000000
sform_xorient  Right-to-Left

Finally, the sform matrix must be equal to the values above. Notice that the diagonal is -2, 2, 2. If your diagonal for some reason reads 2, 2, 2, your x-orientation is Right-to-Left. All images must be in the Left-to-Right format.

Please note that if your image does not conform to these requirements, you won't see it in the image list and it will be deleted from the app to save space!


There are two ways to get images to NeuroPub:

Import images from other apps

This is the preferred method to get images to NeuroPub. You can import images from apps such as Safari, Mail, Dropbox, etc. For instance, you can send yourself an email to your iPhone/iPad with your NIfTI files (both .nii and .nii.gz). You can then tap on the image and get a list of apps that can read NIfTI. NeuroPub will be one of the apps. Just select NeuroPub and the image will be loaded into the image list.

It doesn't matter which app you use to upload images to NeuroPub. You can use Mail, Safari, Dropbox or any other app that can export files.

Upload images through iTunes File Sharing

An alternative way to upload images is to use iTunes File Sharing. This is the same procedure as for uploading documents to Apple's Pages app. Please look at Apple's support page to see how this is done: http://support.apple.com/kb/HT4088

The viewer

If you tap on the example.nii.gz (or any image you have uploaded), it will be loaded into the viewer and visualised as an overlay on the MNI template. You will get into a 2x2 view mode, where you can see the brain in a axial, coronal, sagittal, and 3D view at the same time.

You can now drag the red cursor in the different views to change coordinate and slice locations. The slice locations will change as you move the cursor. Thus, to change slice location in the axial view, you have to move the cursor up or down in the coronal or sagittal view. You can also rotate the 3D view by dragging your finger over the brain. Multi-touch is not included in this version of the app, so you won't be able to pinch in any of the views.

Change view by double tapping

You can go from 2x2 mode to any of the sub-views by double tapping on the view you want to see in more detail. This view will then take over the whole screen. For instance, try double tapping on the axial view. You should now see the axial view over the whole screen. In single view mode, you can change slice location by moving your finger up and down farthest to the right of the screen.You can go back to 2x2 mode by double tapping again on the screen. This way, you can move quickly between the different views.

The 3D brain

The viewer is performing volume rendering in real time. This is done by downsampling the brain to 64x64x64. The viewer displays these as a stack of 2D slices in each direction, which is why your might see some artefacts at an angle of 45° where you are in between two directions (e.g. when you are in between axial and sagittal).

Left is left and right is right - neurological convention

I did not add labels on what is left and right in the viewer, but you can see that by looking at where the cursor is in the 3D view. I have implemented the neurological convention, which means left is left and right is right. Labels will come in the next version.

Controls and buttons


Min/Max Apply

This is where you can enter your own threshold levels of your image. Tap on Apply (or hit return on the keyboard) to apply the new threshold settings. Voxels below the min level will be removed. Voxels above the max level will by default still be visible, but will get the same colour as the voxels at the max level. You can make the voxels above the max level disappear if you like by turning on the Upper threshold tool (read more about this below).

Reset

The tool will automatically set default min and max threshold values the first time you load an image. This is not done when you switch between images. If you have set a min value of 2.3 in one image and you switch to another image, the same min value will be applied on this image too.

However, you can reset the settings to the min and max values of the image by tapping the Reset button, just like when you load an image the first time.

X Y Z

The MNI coordinate and the corresponding voxel value of your selected image are printed next to the Reset button on the iPad and next to the Tools button on the iPhone.


Edit 

The edit button is found in the left corner of the image list. It allows you to delete images from your image list. This button will be disabled if you haven't uploaded any of your own images. The example.nii.gz image cannot be deleted, but will be hidden once you have added your own images.

Reload

If you have uploaded your own NIfTI images and you don't see them in the list, tap on the reload button to make them appear. If they still don't appear, the reason is probably that they don't fulfil the requirements.

View

This button gives you a menu of the different views (2x2, Axial, Coronal, Sagittal, 3D). This is an alternative way of moving between the views. However, as explained in The Viewer section, the quickest way is to move between the views by double tapping.

Colour

This button gives you a menu with different colour maps (Hot, Jet, Autumn, Cool). You can thus change the colour of the overlay by choosing any of these colour maps.

Tools

This button gives you a menu with a number of different tools, which will be described in detail below:

Cursor on/off

You can turn on or off the cursor with this tool. You can still move around the cursor if you turn it off. It's just that it's invisible to you. This is a feature you can use if you want to make a screenshot and don't like to have the cursor overlapping the image.

3D Transparency on/off

This tool allows you to make the 3D brain transparent so you can see regions (e.g. statistical activations) inside the brain. If you have this feature turn off, you will only see the overlay image rendered on the surface of the brain.

This is how it looks like with transparency turned off.

With transparency turned on, you can see the overlay image inside the brain.


3D Overlay alpha on/off

Normally, all the voxels above the minimum threshold level will be 100% opaque and all the voxels below the min level will not be seen at all. If you turn on this tool, the transparency level will be changed so that voxels close to the min level will be more transparent and voxels close to the max level will be more opaque. The image will look more soft with the alpha turned on, which might look better for some images. It is best to use this feature with 3D Transparency turned on.

This image shows how the brain looks like without the Overlay alpha feature turned on.

This image shows how the brain looks like with the Overlay alpha feature turned on.




Overlay mask on/off

If you haven't masked your images, you might have voxels outside the standard brain that are above your minimum threshold value. These voxels will not be shown in the 3D view, but they will be visible in the 2D views. You can mask the overlay image so that only voxels inside the brain are visible in the 2D views by using this tool.

Upper threshold on/off

This feature will allow you to make voxels above the max level to disappear. You can thus remove all positive voxels in a statistical image if you only want to look at negative voxels. If you have loaded an atlas, you can remove all voxels below and above a certain value to make sure you only see the region associated with that value. For instance, if you have voxels with higher values than 2.0 and you enter a max value of 2.0, you will not see these voxels.

Seed voxel in Neurosynth (available in v1.2.2, which is submitted to App Store)

Neurosynth is a database for peak coordinates and corresponding meta-data. With this tool, you can automatically look up co-activation maps in Neurosynth given the MNI-coordinate of the cursor. NeuroPub will open Safari with the corresponding Neurosynth homepage, from which you will be able to download a NIfTI file and open it in NeuroPub. Neurosynth is storing seed-voxel maps with a resolution of 4 mm, so NeuroPub will localise the nearest map given the current coordinate. The maps are in 2x2x2 mm^3.

Email image

This tool will allow you to send the selected image with Email. Both compressed and uncompressed files are supported. For instance, if you are at a conference presenting your latest brain study, you might want to share your statistical results with people that you meet. You can then easily send your NIfTI file to their email address and they can immediately view it on their iPhone if they have installed NeuroPub.

Feel free to comment on this help text if you have any questions.

6 comments:

  1. Having great amount of difficulty to get SPM results to show in the software. Please tell me what I am doing wrong... It is in 32bit float, 91x109x91, with 2x2x2... still, no show. I am so sad :(

    ReplyDelete
  2. Hi. Sorry for the late answer. The transformation matrix has to be -2 2 2 on the diagonal. It won't work if it is 2 2 2.

    ReplyDelete
  3. Hi, the App doesn't seem to work on an iPad 3. After installation I see the example.nii which cannot be removed. The button Edit doesn't work. The installation of an nii file via iTunes doesn't work. I can add a file in iTunes, but after synchronization, the file disappears. Opening an nii file from a mail, the app opens, but not the file. Do you have an idea what this could be? Thank you!
    Jan

    ReplyDelete
    Replies
    1. Hi,
      Sorry to hear you have problems. These are actually not bugs, but I realise I need to make this more user friendly in the next version of the app, because I understand this is confusing.

      I will start with answering the last question: The nii files need to be in 32-bit float, have the resolution 91x109x91 (with voxel size 2x2x2), and the coordinate transformation matrix must be the same as the standard brain that comes with FSL/SPM (with -2 2 2 on the diagonal). Any nii-file that does not conform to this requirement will be automatically deleted to avoid filling up space on your iPad. I will probably change this behaviour so all the images will be listed and not automatically deleted. Instead, you will get an error message telling you what the problem is.

      The edit button does work, but it is disabled if you only have the example.nii image in the image list. This means you cannot delete the example.nii image, but it will automatically disappear once you upload your own images that conform to the requirements I just listed. The edit button will be enabled as soon as you add your own images.

      Are you using FSL or SPM?

      I can help you better if you send an email to me: lars.eric.forsberg@ki.se

      Thanks,
      Lars

      Delete
  4. Hi Lars, congratulations for this very promising took! dont have a question but rather some suggestions that i know may be very difficult to incorporate.
    I am a neuroscience researcher and i see this is the only app designed to seriously deal with neuroimaging.
    I find Neuropub really good, but it is a first priority to allows visualization of different image resolution other than FSL (2x2x2). I really think this will be a great established tool if at least we could automattically reslice the data comming from other packages (spm, freesurfer or 3dslicer for instances) to be appropriately displayed.

    ReplyDelete
  5. useful information on topics that plenty are interested on for this wonderful post.Admiring the time and effort you put into your b!.. UC News App

    ReplyDelete