CrysTBox - Installation

Following lines should guide you through the instalation of CrysTBox, DigitalMicrograph plugin and they should also provide some troubleshooting.

CrysTBox Installation
Installation of DM plugin
Troubleshooting

CrysTBox Installation

The installation procedure may slightly vary depending on your system, whether you choose MCR or WEB installer (see bellow) etc., but the main steps of the installation procedure remain the same as described below.

1. Get installation file

CrysTBox is available on demand. Please contact the author to obtain the installation files.

Installers are available for Windows in 32-bit and 64-bit version. CrysTBox is built using MATLAB Compiler and therefore it requires a package of supporting functions called MALTAB Compiler Runtime (MCR). The installer may or may not include MCR. There are two installer versions available:

MCR (offline) installer - contains MCR, can be used on offline computers (about 700MB)
WEB (online) installer - does not contain MCR, requires the internet connection (about 30MB)

As for the tools (diffractGUI, ringGUI...), both installers provide the same tools and features.

2. Launch installer

Once you have the installer, launch it. You should see this image (on the right) for a while. The lenght of "the wihle" may vary from seconds to tens of minutes. Only MathWorks knows why. Nevertheless, please, be patient.

Note: Before launching the installation of a new version, make sure, that old version of CrysTBox is not running.

Note: It may take the installer some time to appear (tens of seconds, especially for MCR installers). Again, only MathWorks knows why. Please, do not re-launch the installer.

Note: It may happen, that the installer window disapears at the end of this step. Again, only MathWorks knows why. Although there is no sign of the ongoing installation procedure, please do not re-launch the installer, it should reappear in several seconds... or tens of seconds.

Note: If the installer can not be launched, please check whether the installer version (32-bit or 64-bit) fits the version of your operation system.

3. Enter your preferences

You can specify where CrysTBox should be installed, whether to chreate a shortcut and so on.

Note: It may happen that the Next button does not work. If you face this problem, please try to use MCR installer (at least until MathWorks comes up with a solution). According to my experience, this is a problem of WEB installers only.

4. MCR installation (if not installed yet)

CrysTBox needs package of supporting functions - MATLAB Compiler Runtime (MCR). If it has not been installed yet, you can specify the destination folder and you have to agree with the license conditions.

5. Confirmation

Here you can see the installation summary.

6. Wait a minute...

Now, CrysTBox and all other software (if needed) is being installed. It may take few seconds to several tens of minutes depending on the amount of data being installed, on your computer and on your internet connection (in case of the WEB installer).

Note: The installation fails during this step, if an old version of CrysTBox is already running. Once it happens, please terminate the installation, close CrysTBox and launch the installation again.

7. Finished

CrysTBox has been successfully installed.

Installation of DigitalMicrograph plug-in

This guide helps you to install a DigitalMicrograph (DM) plug-in, which allows you to launch the CrysTBox directly from DM.

1. Locate plug-in file

The plug-in file is distributed with the CrysTBox. The file is named CrysTBox.gt1 and you should find it in the folder, where the CrysTBox is installed to. If you have not changed the destination folder during CrysTBox installation, the path should be
C:\Program Files\CrysTBox\CrysTBoxServer\application for 64-bit installation and
C:\Program Files (x86)\CrysTBox\CrysTBoxServer\application for 32-bit version.

Note: The plug-in file distributed with the CrysTBox has been compiled for GMS 2 and will not work in DM 1. Fortunately, Eric Leroy kindly compiled plug-in for GMS 1. Thank you, Eric.

Note: If the plug-in file can not be found in the folder, you can download it here.

2. Copy plug-in file to DM plug-in folder

The file CrysTBox.gt1 needs to be copied to DM plug-in folder. This folder is located in the same folder, where the DM is installed. Typically the path to the plug-in folder looks like
C:\Program Files\Gatan\Plugins

3. Launch DM

Start DM (or restart if already running). There should be a new entry in DM main menu - CrysTBox.

4. Open CrysTBox command file settings in DM

In DM main menu, select CrysTBox / Set path to command file. A dialog box with an edit field should appear.

5.Set path to CrysTBox command file

Specify path to the command file in the DM dialog box and press OK. The path can be found in CrysTBox Server main menu at Settings / Path to command file (see the image).

Troubleshooting

This section addresses problems which you may face during the installation procedure and after successfull installation. If you have troubles during the installation, you can find step-by-step description of CrysTBox Installation.

Installer does not even start

Check whether the installer version matches the version of your operating system (32-bit vs. 64-bit).

Installer button "Next" does not work

However sad it may be, it happens... I'm waiting for MathWorks answer for this bug. According to my experience, it happens for the WEB installers only, so using the MCR installer may help.

CrysTBox is installed, but when launched, only splash screen appears

If you launch CrysTBox a splash screen should appear. After about a minute, the splash should vanish and a graphical user interface of CrysTBox server should occur. If the splash disappears without the CrysTBox server starting up, you might need to clear MCR cache. This problem can also be identified via command line. If CrysTBox is launched via a command window, an error message like "undefined function or variable matlabrc" confirms potential troubles with the cache.

To solve the problem, please delete contents of the cache folder C:\Users\[username]\AppData\Local\Temp\[username]\mcrCache[version]. Then, you sould be able to launch CrysTBox again.

Many thanks to Stephan Steinhauer, who faced this problem and found the solution.

CrysTBox is installed, can be launched, but crashes (software OpenGL)

According to MathWorks, crashes may be caused by drivers of a graphic card. One way how to prevent those crashes is to use software rendering. CrysTBox offers this feature.

Right click on the CrysTBox shortcut and select Properties.

This window should appear.

We are interested in field Target.

Add text opengl software behind the ending quotes. Press OK and try to launch CrysTBox again.

Note, that the settings applies only on this particular shortcut (icon). If the problems presist, please, contact the software author.

DM plug-in can not be found

If the installation folder does not contain the DM plugin file, you can donwload it here:
plug-in for GMS 2
plug-in for GMS 1

Note: If your browser only shows weird characters after clicking at the link above, please set your prowser up so that it downloads the file instead of showing its content... or use different browser. The link itself is all right.

DM plug-in does not work for DigitalMicrograph 1

The plug-in file distributed with the CrysTBox has been compiled for GMS 2 and will not work in DM 1. Fortunately, Eric Leroy kindly compiled plug-in for GMS 1. Thank you Eric.