FAQ: Understanding Memory

When MIPAV performs a function, such as visualizing an image file, it uses RAM on your computer. When you run MIPAV for the first time you must specify the maximum amount of memory (it calls the maximum heap size in the dialog box) that you would like to allocate for MIPAV, so it can take the full advantage of the memory resources available in your machine. The default value is 1000 MB. The amount of memory you can allocate to MIPAV is limited by how much RAM is installed on your system.

MIPAV’s memory allocation is a program-level feature and it affects all users of a given MIPAV installation. You can only change the amount of allocated memory, if you are running MIPAV using an administrative account.

OS	Max memory
Windows 32	1.3 GB
Windows 64	196 TB
Mac OS	196 TB
Linux 32	4 GB
Linux 64	196 TB

Comment: These memory allocations are limited by how much RAM is installed on your computer.

Starting version 5.4.2 the easiest way to allocate memory in MIPAV is to do it when you are installing MIPAV. You can define the memory value in the JVM Memory Limit pane. The default value is set to 1000 MB. In the Pre-Installation summary pane, you can review memory settings, and then return back to the JVM Memory Limit pane and adjust them, if needed.

In case you figured out later that you need more memory, you can still make adjustments using the Check java-runtime Memory Allocation dialog box options. See instructions provided for different operational systems below.

1. Login to your computer under the administrative account, or under the user account who installed MIPAV.
2. Select Help » Memory allocation in the Main MIPAV window. The Check java-runtime Memory Allocation dialog box opens.
3. In the dialog box, change the maximum heap size number so it reflects the maximum amount of memory you might need. Note that for Windows 32, there is a 1.3 GB limit for memory allocation.



4. Click OK to close the dialog box.
5. You must restart of MIPAV for the changes to take effect. To exit MIPAV, select File » Exit. Then, restart the software.

Now, when more memory is needed to perform a certain task, MIPAV allocates it until the memory reaches the maximum heap size you specified. You can also access this dialog anytime and change the memory allocation parameter as you wish.

To change the amount of memory allocated for MIPAV use, you need to run MIPAV using an account that has write-permission to the directory where MIPAV is installed, such as an administrator. The heap size is set in the mipav.lax file located in the directory where MIPAV is installed. E.g. /usr/share/mipav (and not within your own user mipav folder, e.g. ~/mipav). Therefore, you need to run MIPAV with the appropriate permissions to modify files in that directory for the one time when you use the memory allocation tool.

1. Login to your computer under the administrative account, or under the user account who installed MIPAV.
2. Select Help » Memory Allocation in the Main MIPAV window. The Check java-runtime Memory Allocation dialog box opens.
3. In the dialog box, change the maximum heap size number so it reflects the maximum amount of memory you might need.
4. Click OK to close the dialog box.
5. You must restart of MIPAV for the changes to take an effect. To exit MIPAV, select File » Exit. Then, restart the software.

Follow the instructions provided to the Linux users. The only difference is that in Mac OS the mipav.lax file is called mipav.command.lax, but it looks just the same.

To adjust memory settings, MIPAV needs an access to the mipav.lax file located in the directory where MIPAV is installed. That’s why you need the appropriate permissions to make changes in this file. See also: MIPAV LAX files.

mipav.lax file: the allocating memory section

LAX.NL.JAVA.OPTION.JAVA.HEAP.SIZE.INITIAL

# -----------------------------------------

# Java start up heap size

lax.nl.java.option.java.heap.size.initial=1048576000

# LAX.NL.JAVA.OPTION.JAVA.HEAP.SIZE.MAX

# -------------------------------------

# Java maximum heap size

lax.nl.java.option.java.heap.size.max=1048576000

Note: For Mac OS mipav.lax file is called mipav.command.lax, but it looks just the same.

If you change the amount of allocated memory (the maximum heap size) and receive the following error message:

"Heap size settings in the environment startup file either do not match those in the Preference file, or are non-existent. Memory Allocation will display so you can ensure this is correct."

And when you set a new number: in the Change java-runtime Memory Allocation dialog box, the following error message appears:

"Error writing to starting options file. No changes were made."

In order to fix that problem:

This is a common message when you have multiple versions of MIPAV installed on your computer and you switch between them. If you don’t want this warning to show up, you can avoid this by un-checking LAX/Preferences memory check option in the mipav.preferences file. This could be done via the MIPAV Options dialog box.

1. Select Help » Mipav Options in the Main MIPAV window. The MIPAV Options dialog box opens.
2. In the dialog box, go to the Other tab.
3. Un-check the LAX/Preferences memory check box.
4. Click Apply. The change will take place immediately.

MIPAV requires a base of at least 10 Mb of random access memory (RAM). However, to correctly display image files and to quantify the data, you need to allocate more memory, use disk swap space, or install additional memory beyond this base. Each time MIPAV is installed, it always defaults to 100 Mb.

Memory requirements fluctuate depending on the size and number of image files that are open at the same time. Factors affecting memory requirements are the following: 1) the physical size of image files (i.e., 1.2 Mb); 2) the number of images opened, because working on more than one image file at the same time requires more memory.

Note:Java provides a method called Garbage Collector that clears all unnecessarily reserved memory. Generally, the software does this automatically, when free memory becomes very limited. However, you can run the Garbage Collector at any time to free memory (refer to How can I free memory? ).

To determine the amount of additional memory needed:

1. Multiply the size of the largest image file that you want to process by 10.
2. Multiply the results by the number of image files that you want to display simultaneously.
3. Add this amount to the 10-Mb base memory to result in the total amount of memory typically needed.

If an image file is 2 Mb and you only want to display one image file at a time, you must allocate an additional 20 Mb of RAM to the base memory of 10 Mb to result in a memory requirement of 30 Mb.

2 Mb Size of image file x 10

---

20 Mb Memory required for displaying and processing 1 image file

+

10 Mb Base memory required for running MIPAV

---

30 Mb Total memory required

If the largest size image file is 2 Mb and you want to display 3 image files simultaneously, multiply 2 Mb by 10. Then multiply that sum by 3. Add that total to the base memory of 10 Mb to yield a memory requirement of 70 Mb.

2 Mb Largest size image file x 10

---

20 Mb Memory required for displaying 1 image file x 3 Number of images to display and process simultaneously

---

60 Mb Memory required to display 3 image files

+

10 Mb Base memory required for running MIPAV

---

70 Mb Total memory required

In the main MIPAV window, select Help » Memory Usage (or press Ctrl+M). The Memory Monitor dialog box appears. The dialog box shows how much memory is allocated and the amount of memory that is being used. The graph displays a pictorial representation of the ratio of allocated memory and amount of memory used. It shows the memory usage during the past 3 minutes and 45 seconds.

Note: You can leave this window open if you want to constantly monitor your memory resources.

As Java-based programs run, they often leave old variables, objects, or constructors in memory. For instance, if you delineate a VOI, the coordinates of the contours may remain in memory even after you close the image. Java provides a method called the garbage collector (or memory recycling) that automatically freeing objects that are no longer referenced by the program and clears all unnecessarily reserved memory. Generally, the software does this automatically when free memory becomes very limited. However, you can run the garbage collector at any time to free memory by clicking the Garbage Collector button.

• Click the Garbage Collector button on the main MIPAV window.
• Select Help » Memory Usage in the main MIPAV window. The Memory Monitor dialog box appears. Click Free Memory. The system clears all unnecessarily reserved memory.

This video tutorial explains how to load images into MIPAV and change the memory allocation - play.

• Getting Started Quickly with MIPAV
• Allocating Memory in MIPAV
• Opening and loading image files

Next: FAQ: Customizing MIPAV