| Scripting Resources for DigitalMicrograph™ |
GMS 3: Free Offline version
DigitalMicrograph (DM) is part of the Gatan Microscopy Suite (GMS) of software. The GMS installer contains all Gatan's software, such as drivers, plugins and tools for the various cameras and spectrometers it makes. This make the GMS installer quite large (ca 1GB). The installer works by first looking for installed licenses for various components in GMS. It then installs only those components for which a license is found. Gatan kindly make available a free offline version of DM. In order to install this, a free offline license must be installed first. Although the GMS installer is large, the DM component only takes up about 150MB on your hard disk.
The free offline version of DM will install with a basic set of functionality. This will allow users to open and manipulate images and spectra saved in Gatan's proprietary formats (.dm3 and .dm4). However, if you have specialised plugins installed on your online (microscope-based) DM, such as EELS and Spectrum Imaging, then this functionality will not be available in the offline version. Additional functionality can be added into your offline DM by installing scripts and plugins from third party users. For example, EELSTools and SITools plugins available on this site, will provide some of the functionality of the online plugins from Gatan, so that you can carry out basic processing away from the microscope.
There (were) two versions of DM available in GMS 2 and GMS 3. GMS 3 was released around 2016 and has a radically different user interface to GMS 2. That said, the vast majority of the functionality is similar to GMS 2 and GMS 3 is fully backwards compatible with GMS 2. Gatan now seem to now offer free licenses for GMS 3.x only. Although the GMS 2.3.2 installers are still on their ftp download page, there doesn't seem to be an avenue for sourcing a free license with which to install it. I guess Gatan want to encourage users to move to their latest software. Apart from having to learn the new interface the biggest issue is that GMS 3 is only compatible with 64 bit operating systems. So if you have a 32 bit version of Windows, you will have to install the 32 bit version of GMS 2 (if you have a valid license).
To source a free offline GMS 3 license go to the Gatan download page
Click on the GMS 3 button and you will be prompted to enter your personal details to register for a license. Once these are entered and submitted you will be presented with a download page from which to download the license. Download this to your desktop. The file will be called something like: Gatan_Free_Offline_3.x.y_64-Bit_Suite . .
At the bottom of the download page is a Download button which links to the GMS Installer - click on the download button and download the GMS 3.x installer by clicking on the GMS_3_2_1_64-Bit.exe link . Download the GMS installer to your desktop. This is a big file, ca 1GB. Make sure the license file version number (GMS 3.x.y . . ) matches that of the GMS installer you are using. This license will only work with GMS 3. It will not work with GMS 2. Note the software version number (3_2_1) will increment as Gatan release newer versions.
Keep a copy of the license and installer file somewhere safe, in case you need to reinstall it.
Since GMS 3 is only offered in 64 bit format, it cannot be installed on 32 bit operating systems (see GMS 2 below for 32 bit options).
Create a folder called 'MyLicenses' on your desktop and move the license file you just downloaded to it. You will need a decompression utility to decompress it - such as 7-Zip, PeaZip, WinRAR etc. If you do not have such a utility already installed, they are available free from the internet. Right click on the Gatan_Free_Offline_3.x.y_64-Bit_Suite . . license file which you just downloaded and decompress it. It will decompress to create several files including the license and the license installer program.
A note on the LicenseInstaller.exe program. The program itself does not contain licenses. It merely looks for licenses within its bounding folder and installs those. This means that you MUST have license files within the same folder as the LicenseInstaller.exe. Unfortunately, the LicenseInstaller will happily run and appear to work normally, even if no licenses are found. So you may think that you have installed licenses, but you haven't. The GMS installer will then run but will provide no selected components to install - because the licenses are missing.
Double click on the LicenseInstaller file. If you get prompted to install .Net Components - follow the links. You will need to restart Windows after installing .Net. You should then run Windows Update to ensure that the .Net components are fully current. If they are not, download and update and restart until they are. When the license installer runs then you will be presented with a dialog which contains a large 'Install Licenses' button. Click on that and the dialog will then close.
Where do the licenses get placed? In the case of GMS 3, the license installer places the licenses in a temporary folder with the path:
/Local Disk/Users/UserName/AppData/Local/Temp/_GatanInstall.
UserName is the name of your user account. The AppData folder is hidden by default. You can make it visible by selecting the Folder View options control panel in Windows Preferences and setting the 'Hidden Files and Folders' option to be shown.
Create a folder on the desktop called 'MyInstaller or similar. Move the GMS 3_2_1 _64-Bit.exe installer into this folder. Double click on the installer to decompress it - leave the path as is so that the files decompress into the 'MyInstaller' folder.
Run the GMS Installer by right clicking on the 'Setup' program and selecting Run as Administrator. The installer looks for the license files which were installed earlier and moves them to their final home which is:
/Local Disk/ProgramData/Gatan/Licenses
The folder ProgramData is hidden by default, but if you set the folder view options as described above you will be able to see the contents.
When the SetUp program (GMS Installer) is run, provided valid licenses are found, the installer will list all the components it will install. DigitalMicrograph Offline should be selected automatically. If it is not, then there is a problem with license installation. Check the above location to make sure licenses are present. If you run into problems, you can try installing the licenses by manually creating a folders to create the path:
/Local Disk/ProgramData/Gatan/Licenses
Then manually copy the two license files to the Licenses folder in the above path. The license files have the same name (Gatan_Free_Offline_3.x.y_64-Bit_Suite . ) - one a .glc file (the license) and another a text file describing the contents. Note, if you are manually creating folders, ensure the folder names are spelled exactly as shown above. See license troubleshooting at the end for more information.
GMS 2: Free Offline version
This is available in 32 bit and 64 bit flavours. The functionality of the two flavours is identical, except that the 64 bit flavour will handle very large files (>2GB). For most users this doesn't matter. The 32 bit flavour can be installed on computers with EITHER 32 or 64 bit Windows (XP, 7, 8, 10) operating systems. The 64 bit flavour can ONLY be installed on a computer running a 64 bit version of Windows. If you are unsure about which flavour to install, install the 32 bit GMS as it is universal. If you do not know the type of Windows you are running, you can find out by right clicking on the icon of the computer on the desktop and select 'Properties'. In the information displayed should be the 'System type' which will be listed as either 32 or 64 bit.
Since Gatan seem to no longer provide GMS 2 licenses, you will only be able to install this version if you have already have a copy of the GMS 2 licenses and installer. The license installer and GMS installer can still be downloaded from the Gatan website - the final version released being GMS 2.3.2. However, without valid licenses, these installers are useless.
This guide assumes that you already have valid GMS 2.3.2 licenses and have the license installer and GMS installer.
On the Desktop create a folder called 'MyLicense' or similar and copy the file GMS_2_3_2_LicenseInstaller.exe to it. This file is compressed and you will need decompression software to unpack them, such as WinRAR. Next, copy the license files into the 'MyLicenses folder'. There are two files called 'GATAN_FREE_Offline_64-Bit Suites. One is a glc file (the license) and the other is a text file describing the contents. The licenses should not be in their own folder, they must sit directly in the 'MyLicenses' folder. The license installer will look for licenses within the same folder as itself. If it does not find licenses it still runs and appears to work - only it doesn't.
Double click on the GMS_2_3_2_LicenseInstaller.exe and click on Install, leaving the default path as is. The license installer files will be decompressed into the MyLicense folder.
Create a folder on the Desktop called 'MyInstaller' or similar and copy the file GMS_2_3_2_64-Bit.exe installer to it. Double click on the file and select Install, leaving the default path as is. The Installer files will be decompressed into the MyInstaller folder.
If you have anti-virus software installed, it may be a good idea to deactivate it. If you have an existing version of DM installed, this installer will overwrite it. Any licensed plugins etc you have installed will be lost, so only proceed if you are happy to loose your exisiting setup. You will need administrator privileges to install this software. If you are working on a managed computer you will need to get administrator assistance to proceed.
The decompressed Licence Installer may need some .NET Framework components installed - which you may not have on your PC. If you run the decompressed licenseinstaller.exe and are prompted to update the .Net Framework, follow the prompts to update select the option 'Download and install this feature'. You will need internet access to download the files. Once prompted that the required files have been installed, you must restart your PC. From the Windows preferences select the Windows Update option to see if .Net needs updating further. If you see there are further updates for the .Net Framework available - download and install these (it may take some time) and restart. Once you have ensured that the .Net Framework is up to date, you can try to run the licenseinstaller.exe again.
Run the decompressed LicenseInstaller, by right clicking on it and Running As Administrator, it puts up a dialog with a large button saying 'Install Licenses'. Click on this button. The installer copies the licenses to the hard drive and the dialog closes. You are now ready to run the GMS Installer. One of the problems with the license installer is that it can seem to run perfectly. However, when you come to run the GMS Installer it doesn't select any software to install, because the licenses haven't actually been installed. If you run into problems see the License Installation - troubleshooting below.
Open the folder called 'MyInstaller' on your Desktop. Right click on the 'Setup' program and select 'Run as Administrator'. The GMS Installer should find the previously installed licenses and then automatically select DigitalMicrograph Offline as the component to install. If this option is not selected automatically, then you have a problem with the license installation.
GMS 2/3 Offline License installation - troubleshooting.
The big problem with the license installer is that it appears to work, even if the license files have not been included within the bounding folder. You can manually install license files and this often overcomes such problems.
Installed licenses are stored in folders which are hidden by default. In Windows Preferences set the Folder View Options so that hidden folders are shown. Once this is set you should see a folder called AppData appear on the Local Disk. Navigate to the folder and see if licenses are present in the following directory
/Local Disk/ProgramData/Gatan/Licenses/
There should be two license files there called: Gatan_Free_Offline_64-Bit_Suites.glc and Gatan_Free_Offline_64-Bit_Suites.txt (these are GMS 2 licenses. GMS 3 licenses have the version number included in the filename).
The version of the license can be read by opening the License txt file. It should match the version of GMS you are attempting to install.
If the license files are missing or if the entire Gatan/Licenses path is missing, it means the license installer has not worked correctly. In which case you can manually install the licenses by creating the . . . /Gatan/Licenses path within the /Local Disk/AppData/ folder. Simply create a new folder within AppData and call it Gatan. Then open the Gatan folder and create a new folder called Licenses. Then copy over the two license files into the newly created Licenses folder - note the two license files must not be contained within their own folder, they must be placed directly in the Licenses forlder which you just created. You should then find that the GMS Installer will work correctly, in that when it is run it automatically selects the DigitalMicrograph Offline software as the installation option.
If the two license files are present in the correct path, but the GMS Installer does not correctly select DigitalMicrograph Offline as the component to be installed, there may be a problem with the license files, such as a corrupted file or a version mismatch. In which case you might try copying the licenses from a free offline version of DigitalMicrograph which you know to be good and then attempt to run the installer. If you do that you can check the version of the working DigitalMicrograph Offline copy, by either looking at the flash screen which appears when the software is launched or by selecting 'About DigitalMicrograph' from the DM Help menu. Ensure license and GMS installer versions match.
Since GMS 2 licenses are no longer available online, I'd recommend keeping a copy of the licenses/installers somewhere secure, in case you need to reinstall.
I have tested this approach with both the free offline versions of GMS 2 and 3 and found it to work.
In terms of scripting, there are some minor differences between the two GMS versions. As these come to light, I will log them along with any scripting workarounds, at the following tutorial page.