I expect version 5.5.0 to be the final release of Figure Composer. I plan to maintain this website through the end of 2025, and I have pushed the code to a Github repository in case anyone would like to clone the repo and continue its development.
Figure Composer and the related Matlab utilities described in this user guide may be downloaded from the file cabinet at the bottom of this page. The software and related documentation is developed, maintained, and owned by the Lisberger laboratory. It has been made available here free of charge to support other members in the scientific community who are interested in using these applications to construct scientific figures for publication.
If you choose to download any software product from this site, you must read and abide by the following disclaimer. In addition, be sure to review the system requirements and the relevant download instructions.
FigureComposer and its supporting Matlab utilities are developed and maintained in-house for use by members of the Lisberger laboratory. Selected applications have been made available here for the greater scientific community. By downloading and using any of these applications, you agree that you will not hold the Lisberger laboratory nor the Figure Composer developers liable for any malfunction in the program or the system on which it is installed, nor any loss of data/information resulting from the use of the program.
Operating system: Windows 10/7 (64- or 32-bit); Mac OS X 10.6+; Linux. Feel free to try FC on other versions of these and other OS platforms (as long as a Java runtime is available for the platform), and report any problems you encounter. We do not have access to nor the time necessary to test thoroughly on every OS platform out there. We currently develop FC on a MacOS Catalina (10.15.3) system, and test it on that system and on a Windows 10 1601 LTSC 64-bit desktop.
Java Runtime Environment (JRE): You must separately install a JRE compatible with the host OS in order to run FigureComposer. As of version 5.5.0, the program requires a Java 11 JRE. The application is code-compatible with (and was compiled against) a Java 11 development kit (JDK), but it should run on newer versions of the Java runtime.
Versions 5.2.x - 5.4.x are JDK8 compliant and require a Java 8 JRE or better.
Versions 5.1.x were compiled against a Java 7 JDK and required a Java 7 JRE or better. Do not use a Java 9 or later runtime with V 5.1.x; certain key features (macOS and Windows Desktop integration, FIG file import) are broken.
Versions 5.0.2 and earlier are no longer supported nor available for download. These were compiled against a Java 6 SDK and required Java 6 or better.
Processor/memory: For best results, we recommend a Windows system with an Intel Core 2 Duo-class processor rated at 2GHz or better and at least 2GB RAM, or a Mac OS X system with an Inter Core 2 Duo-class processor or better and at least 2GB RAM. Performance may also be affected by the quality of the system's video card, whether or not it borrows system RAM for use as video memory, etc.
Matlab utilities like matfig2fyp() rely on supporting Java archive files (JARs) that accompany the FigureComposer installation. Matlab comes configured with its own default Java Runtime Environment (JRE), which has been Java 8 since at least R2020a.
Be sure that the Java version of the FC supporting JARs <= the version of the JRE that Matlab is using, or you'll see confusing "Java class not found" errors when you try to run matfig2fyp().
FC 4.x - 5.0.2: Java 6 or better JRE required.
FC 5.1.x: Java 7 or better JRE required.
FC 5.2.x - 5.4.x: Java 8 or better JRE required.
FC 5.5.x or laterr: Java 11 or better JRE required.
The Matlab command jenv will print information on the JRE in use, and the same command can change the JRE. Note that the default JRE bundled with Matlab since R2019b is Java 8-compliant, and that is unlikely to change. However, since R2023a, Matlab supports using an OpenJDK 8 or 11-compliant runtime like Amazon Corretto. If you want to use the supporting JARs that come with FC5.5.x or later, you must be running Matlab R2023a or later.
FigureComposer was originally developed as a Java application to take advantage of Java's "write once, run everywhere" philosophy. Of course, to make that happen, you must install a Java Runtime Environment compatible with your OS platform of choice. When FC development began (as Phyplot) in 2003, the JRE was at version 4. By the time FC 1.0 was released in 2007, it required Java 5. Major Java version releases came out every several years or so, but Sun Microsystems (and, later, Oracle) would continue to provide security and "patch" updates to older versions so that application developers had plenty of time to update their programs as necessary. Apple provided its own proprietary Java runtime for MacOS, but abandoned it in 2013 with Java 6, handing over the reins to Oracle. Since it acquired the rights to Java, Oracle has provided a free JRE binary for Windows, Linux, and Mac OS -- along with free updates -- for successive major versions 6, 7, and 8. Up until recently, Oracle was probably the best source for a Java runtime for those major OS platforms.
However, the Java ecosystem changed substantially in 2017. Now a feature release occurs every six months, with a few patch and security updates between each six-month release. Certain releases are targeted for "long term support", such as Java 8 and Java 11; security and patch updates will be offered for LTS releases for 3 or more years after the initial release. In April 2019, Oracle changed its licensing terms for Java. Its proprietary implementation of Java is no longer free for commercial use (although their Java 8 JDK remains free for personal desktop use until Dec 2020). Oracle is encouraging non-commercial users to remove old versions of the JRE/JDK and use an open-source release based on the OpenJDK project. Various vendors, including Oracle, provide OpenJDK-based implementations for Java 8 (and later versions) that are free to install and use. For example, Amazon Corretto 8 is the OpenJDK-based implementation of the Java 8 specification and is offered for MacOS, Windows, and Linux. Amazon plans to support Corretto 8 through at least July 2026, and Corretto 11 through October 2027. Given the changes in Oracle's licensing terms for its proprietary JRE, we recommend switching to an OpenJDK-based binary like Corretto. Check out this article for more information.
As of Feb 2020 and FC v5.2.0, all users are encouraged to update their Java runtime environment to the latest available Java 8 update. The OpenJDK-based implementations are free and should be as performant as Oracle's proprietary implementation. We encourage users to choose LTS releases of the Java runtime, Java 8 or Java 11, rather than the very latest feature release (Java 14 is scheduled for release in Mar 2020). We have tested FC 5.2.0 successfully on the Amazon Correto Java 8 and Java 11 runtimes under both macOS and Windows 10 64-bit.
As of FC v5.5.0 (not yet released), FigureComposer is built with a JDK11-compliant compiler and requires a Java 11 runtime enviroment.
The FigureComposer figure document, ending with the .fyp extension, is a text file with XML markup conforming to the informally specified FypML "dialect". Previous versions of the application did not associate the .fyp file type with the program -- so users could not start it simply by double-clicking on any file ending in that extension. File associations are a very platform-dependent feature, and their implementation is especially cumbersome on the registry-happy Windows OS. FC versions since 4.1 have addressed this issue, at least for Windows and Mac OS X.
For MacOS, it was a matter of packaging FigureComposer as a MacOS "application bundle" and explicitly defining the file type (including a document icon) in the Info.plist resource within that bundle. The installation procedure remains unchanged; the file association should "just work". You will notice that .fyp files in the Finder now sport FigureComposer's application icon, and that you can double-click any .fyp file to start the program. Furthermore, if the program is already running, double-clicking a .fyp file in the Finder will activate the app, bring it to the foreground, and open the figure file that was clicked.
For Windows, more extensive changes were necessary. Java's recommendation is to deploy the desktop application via Java Web Start, but that technology is fraught with issues and implementation difficulties (and, as of Java 11, JWS is no longer available). Instead, we chose to wrap FigureComposer as a Windows executable using the WinRun4J package, and distribute it -- along with the Matlab supporting files -- via a single self-extracting installer (compiled using Inno Setup) that makes the necessary changes in the Windows registry to configure the .fyp file type association. Once you download and run the installer, you'll find FigureComposer in the Start Menu (or you can optionally add a desktop icon during installation) and run it like any other native Windows application; you can also pin it to the task bar in Windows. You get the same double-click behavior as described above for MacOS; also, the application shows up in the Windows Task Manager as FigureComposer.exe instead of the more generic javaw.exe.
Distributing FigureComposer as an application bundle for MacOS and a self-extracting installer in Windows has caused some headaches in the past. I highlight these in case anyone is using FC on older systems.
Apple officially ended support for its proprietary implementation of the Java Runtime Environment (JRE) in 2013. Oracle purchased Java from Sun Microsystems and maintains reference implementations of the JRE for the major operating systems, including MacOS. However, Oracle did not preserve Apple's approach to packaging a Java application as an "application bundle"; the bundle structure changed, as did the application launcher (a native executable) within the bundle. Therefore, in order to continue support for Apple Java 6 as well as Oracle Java 7/8, we provided separate application bundles for each JRE target for FC versions 4.7.2 - 5.0.2.
Java 6 is very outdated, and all users are strongly encouraged to migrate their MacOS workstations to a Java 8 runtime environment or better. In fact, we have found that, on MacOS 10.12 (Sierra), the Apple Java JRE-compatible releases of FC crash during startup, probably due to a problem with the native executable file (JavaApplicationStub) that launches an Apple Java 6 program. For this reason, we will no longer support the Apple JRE as of FC version 5.1.0.
The Oracle-supplied application launcher cannot find JREs from other vendors. When I installed Amazon Corretto 8 on MacOS Catalina and tried to run FC, the application failed to load and a dialog box reported "JRE Load Error". Basically, Oracle's application launcher is not good at finding the file system locations of alternate JRE implementations. To resolve this problem, as of FC 5.2.0, that launcher was replaced with an executable bash file ("universalJavaApplicationStub") that does a better job of finding different JRE installations on a MacOS system.
Prior to V5.1.0, the Windows self-extracting installer only supported installing a 32-bit Windows launcher for FC. If you installed this on a 64-bit system with a 64-bit JRE, FC would fail to start with a cryptic "Failed to find Java VM" message. This is because the 32-bit launcher cannot find or load the 64-bit Java Runtime Environment. Starting with V5.1.0, the installer now supports both 32-bit and 64-bit installs. The installer does NOT support installing the 32-bit launcher on a 64-bit system; it is expected that the 64-bit JRE will be installed on a 64-bit Windows system.
Check one of the sections below for the name of the ZIP distribution archive to download for your OS platform. Download the archive from the appropriate drive folder at the bottom of this page, and follow the platform-specific instructions. The distribution ZIP file name includes the application name, the targeted OS platform, and the release/version number N.M.R. For example: FigureComposer_win_430.zip, FigureComposer_mac_430.zip.
Only versions 4.7.3 and later are available for download here, and these instructions apply only to these more recent releases. Contact the developer if you need an older release; download instructions pertaining to older releases are here.
If you plan to use any of the utility functions in the Figure Composer support package for Matlab, be sure to review the usage information on the Matlab Utilities page.
Download and unzip the archive FigureComposer_win_NMR.zip for the desired version, then open the resulting folder and run the self-extracting installer, FigureComposerSetup.exe. No administrator privileges are required. Select which application components you want to install. The installer makes the program available only to the current user. You'll find the installed components at Start Menu | All Programs | Figure Composer. You can pin FC to the task bar, and you can uninstall it like any other Windows application.
NOTE: The installed program, FigureComposer.exe, is a small Windows executable that locates the installed Java Runtime Environment (JRE) and uses it to launch FC. If it cannot find the JRE for whatever reason, it will abort with the error "Failed to find Java VM, "JRE load error", or a similar error message. You can still run FC in this scenario, but you must locate the installed JAR file and launch it manually from a Windows Command Prompt via the command java -Xmx1024m -jar figurecomposer.jar. However, starting FC this way means it will lack certain desktop integration features available when it launches as a native executable.
Download and unzip the archive FigureComposer_linux_NMR.zip for the desired version. A single FigureComposer folder is created; it contains everything needed to run FC, and the Matlab support package is found in the matlab subfolder. Open a C-shell terminal, navigate to the FigureComposer directory, and run launchFC. This short script contains a command that launches the program: java -Xmx1024m -jar figurecomposer.jar. Note: On Ubuntu Linux, you may need to rename this file launchFC.sh.
Download and unzip the archive FigureComposer_mac_NMR.zip for the desired version. Move the extracted folder, FigureComposer, to your Applications directory. Within this folder is the FigureComposer.app application bundle, along with a matlab subfolder containing the Matlab support package. Drag the app bundle onto the Dock for convenient access.
NOTES:
In OS X Mountain Lion (10.8) and later, Apple ships the OS configured to prevent you from opening any software that was not downloaded from the Mac App Store. Thus, you will be unable to run FigureComposer, unless you make a change in your System Preferences. Under the Security & Privacy section, set "Allow applications downloaded from" to "Anywhere". If you would rather not open up your machine in this way, you can instead choose to make an exception only for FC. Right-click on the downloaded app, choose "Open" and confirm that you would like to open and run the app. You should only have to do this once!
For versions prior to 5.1.0, there are two ZIP files: *_mac_NMR.zip for systems still using Apple's own Java 6 JRE; *_mac_j7p_NMR.zip for Oracle JRE 7 or better. Starting with version 5.1.0, the Apple Java 6 JRE is no longer supported, and there is only one Mac-specific archive, *_mac_NMR.zip.
Starting with MacOS 10.14 (Mojave), applications may access the user's protected folders -- such as Desktop, Documents, and Downloads -- only with the user's permission. When the application first attempts such an access, MacOS intervenes -- raising an AppleScript dialog requesting permission from the user. If the user grants access, MacOS remembers that fact. Unfortunately, this mechanism only works for application binaries, but FC 5.2.x is launched with a bash script. There are workarounds to address this issue: (1) Avoid keeping your FC figure files under any of the protected folders. (2) If that's not possible, you could grant the bash executable itself "Full Access" to the machine (in the Security & Privacy section of System Preferences) -- but that's a security risk and is not recommended. (3) As of FC 5.3.0, the MacOS application bundle is available in three versions -- one with the bash script launcher, one with a binary application launcher (essentially a compiled version of the script) compatible with MacOS 10.15 (Catalina), and another compatible with Mac OS 11.0 (Big Sur). The latter may also work on Mac OS 12.0 (Monterrey) and Mac OS 13.0 (Ventura), but that has not yet been tested. If you need to access figure files in any of the protected folders and have a supported OS version, then try the corresponding app bundle:
FigureComposer_mac_NMR.zip -- FC version N.M.R with the bash script launcher.
FigureComposer_mac_catalina_NMR.zip -- FC version N.M.R with a binary launcher targeting Mac OS Catalina.
FigureComposer_mac_bigsur_NMR.zip -- FC version N.M.R with a binary launcher targeting Mac OS Big Sur.
Memory usage concerns. With the introduction of the matrix-like heat map data, it is rather easy to tax the default maximum heap size of 64MB allocated to the Java virtual machine (JVM). In recent testing, we got the dreaded "OutOfMemoryException" when trying to load the dataset for a 1000x1000 heat map. The recommended workaround is to increase the JVM's maximum heap size to 1024MB. That is the reason why the JVM option "-Xmx1024m" is included in the command that starts Figure Composer. The Mac OS X application bundles and the Windows Win32 executables are already preconfigured to set the maximum heap size to 1024MB.
Click on the folder icon below containing the version of Figure Composer that you need. A new browser window opens displaying the contents of that Google Drive folder, from which you can download the ZIP archive for your operating system. If the Drive folder is in grid view, hover over the item that contains the ZIP file you want, and a download arrow appears in the top left corner. Click on it to start the download. If the folder is in "list view", hover over the relevant list item and you'll see the download arrow appear on the right; again, click on it to start the download.