Installation / Execution

Shortcuts To Installation/Execution Instructions

Computer Operating System
Windows
Macs
Linux, Solaris, and Others

Table of Contents

System Requirements

Aperture Photometry Tool (APT) is an all-Java software implementation. There are no software dependencies on other astronomical packages or libraries. However, you will need to have a recent version of the Java Runtime Environment (JRE) installed on your machine. The latest version of APT (v. 3.0.9) was compiled with JDK 13 (Java Development Kit). APT will also run under higher Java versions because of Java’s forward compatibility.

APT can be installed and run on any computer with the JRE installed (or JDK, which includes the JRE). This includes, but is not limited to, machines running Mac, Windows, Linux, and Solaris operating systems. The minimum memory requirement is probably less than 500 MBytes. APT’s basic functions can be utilized on machines with relatively small memories to analyze portions of very large images, which is effected by setting the maximum image size under APT’s preferences menu to as little as 500 pixels on a side.

APT can be installed as a double-clickable application or can be executed from the command line. The former is particularly easy for Windows and Mac machines. In order to do the latter, the java command must be in the system’s path. To determine whether this is the case, type the following command in a terminal window:

java -version

You should see a response like

java version "13" 2019-09-17
Java(TM) SE Runtime Environment (build 13+33)
Java HotSpot(TM) 64-Bit Server VM (build 13+33, mixed mode, sharing)

The 64-bit JVM (Java Virtual Machine) is required for APT, and the java command’s -Xmx option can be changed to allocate a larger amount of memory if APT is used to analyze extremely large images.

APT Packages

The appropriate APT package should be chosen for the target machine. The *.tar.gz package can be installed on all machines (but the *.zip package is more convenient for Windows machines), and is suitable for users running APT from a command window, but a slightly more complicated installation procedure must be followed in this case. Most users will want to install APT as a double-clickable application, however. In this case, the *.zip package for Windows machines or the *.dmg package for Macs should be downloaded.

APT PackageMD5 Checksum
All machines (except get the *.zip package for Windows): APT_v3.0.9.tar.gz66c8014589ba6da5736aeeb44aaae747
Windows machines: APT_v3.0.9.zip2c61ac7546d7bcc9026a66beba10113c
Mac, regular-sized GUI: APT_v3.0.9.dmg8459d33655a698c413edbc11a15ac5c0

Basic Installation and Execution Instructions

APT packages can be downloaded from here.

Windows Machines

The easiest way to install and execute APT on a Windows machine is as follows:

  1. Download the *.zip file.
  2. Unzip the file to a sensible location of your choice, perhaps the Desktop.
  3. Bring up a Windows Explorer window, navigate to the installed
    location, and double-click on the APT.exe Application file (which has the red and green APT logo as its icon).

A shortcut to APT.exe can be created and placed on the Windows Desktop for convenient access. Simply mouse-click on APT.exe with the right mouse button and choose “Create Shortcut”, and then drag the resulting “Shortcut to APT.exe” file to the Windows Desktop.

Please be careful to not double-click on either APT.jar or APT.bat. The former will launch APT, but insufficient memory will be allocated for large images. The latter will launch APT properly, but only if the Java bin directory is in the path of the operating system.

Macs

The easiest way to install and execute APT on a Mac is as follows:

  1. Download the appropriate *.dmg file.
  2. Double-click on the *.dmg if the Mac does not automatically open it.
  3. Drag the “Aperture Photometry Tool.app” application to the /Applications folder.
  4. In the Mac’s Finder tool, navigate to the /Applications folder, and double-click on the “Aperture Photometry Tool.app” application.

APT can be placed on the Mac’s dock for convenient access. Simply drag the APT folder from the /Applications directory over to the dock and hover to allow time for the existing dock icons to “make room” for APT.

See FAQ related to MacOS Sierra, if applicable.
Or, see FAQ related to MacOS Catalina, if applicable.
If you encounter problems installing APT on your Mac (only for MacOS versions prior to Catalina)…
On newer Macs, the following error may be displayed upon attempting to install the software: “Aperture Photometry Tool” is damaged and can’t be opened. However, the file is not damaged (and one can verify the MD5 checksum), and should work just fine after the security settings are (temporarily) loosened. To do this, navigate to menuSystem Preferences > Security & Privacy > General and change the radio-button selection under section “Allow apps downloaded from” to “Anywhere”. Please look at this note for further details.However, the above workaround does not always work for the latest versions of Mac OS X. Here are two more things to try (try one, and, if that does not work, try the other):Some later versions of Mac OS X have removed the aforementioned “Anywhere” option for downloaded Apps under menuSystem Preferences > Security & Privacy You can try doing the following terminal fix to get the Anywhere option back:Close System preferencesOpen a Terminal windowEntersudo spctl –master-disableEnter PasswordClick onSystem Preferences > Security & Privacy > AnywhereOpen APTTo restore the higher-security setting, clickSystem Preferences > Security & Privacy > Appstore and Identified DevelopersThis covers it nicely:
https://www.tekrevue.com/tip/gatekeeper-macos-sierra/
Thanks to Ross Cutts for this valuable bit of information in getting APT to work on his Mac OS Sierra machine.Or, try opening a Terminal window and entering the following command (you may need to modify the path depending on your specific set up):xattr -cr /Applications/Aperture\ Photometry\ Tool.app/ This was reported to work by Yoonsoo P. Bach for a Mac running OS Yosemite. The original URL for this tip is
http://osxdaily.com/2019/02/13/fix-app-damaged-cant-be-opened-trash-error-mac/

Linux, Solaris, and Other Machines

This section illustrates a general procedure for installing APT on computers with UNIX-like operating systems, including Macs, that meet the above system requirements (and even Windows machines, although advanced knowledge of Windows is required, including using batch files, setting environment variables, executing DOS commands from a Command-Prompt window, possibly using the DOS edit command to edit the APT.bat file). The following basic steps are involved (and more details are given afterwards):

  1. Download and uncompress the *.tar.gz file.
  2. Copy the file to an installation directory, like ~/Applications in the example below (the ~ symbol means the user’s home directory).
  3. Extract the contents of the *.tar file after uncompression.
  4. Set environment variables according to the details of the installation.
  5. Execute the appropriate script to launch APT (APT.csh for UNIX-like operating systems or APT.bat for Windows machines).

Note: it has been reported that Chrome gunzips the *.tar.gz file, but does not remove the “.gz” suffix from the filename, so you may have to manually rename the *.tar.gz file to *.tar. Alternatively, use Firefox instead to download the *.tar.gz file.

Installation instructions (and uninstalling previous version of APT): 

cp APT_v3.0.9.tar.gz ~/Applications
cd ~/Applications
rm -rf APT_v2.8.4 (if you installed it here last time)
gunzip APT_v3.0.9.tar.gz
tar xvf APT_v3.0.9.tar
rm APT_v3.0.9.tar

Now, you need to set up your environment. If your default shell is bash, add these lines to your ~/.bash_profile file (or change from 2.8.4 to 3.0.8 if you installed the previous version of APT): 

export APT_HOME=/Applications/APT_v3.0.9
export PATH=$APT_HOME:$PATH
# Set APT_ARCH to either MAC or LINUX or UNIX or WIN
export APT_ARCH=LINUX

Special note: If your machine is running Ubuntu Linux, then consider adding the above lines to ~/.profile instead of ~/bash_profile.

If your default shell is csh or tcsh, add the following lines to your ~/.cshrc file (or change from 2.8.4 to 3.0.9 if you installed the previous version of APT): 

setenv APT_HOME /Applications/APT_v3.0.9
setenv PATH ${APT_HOME}:${PATH}
# Set APT_ARCH to either MAC or LINUX or UNIX or WIN
setenv APT_ARCH LINUX

Execution instructions:

  1. Bring up a new terminal window.
  2. Change to a working directory.
  3. Execute the following command in the new terminal window:
APT.csh

Advanced users are encouraged to examine shell script APT.csh to see how it uses the java command to execute the APT jar file, along with the memory setting that is specified. This script can be modified by users to suit their particular requirements.

Troubleshooting Your Installation

If APT does not work as a double-click application on your Mac or Windows machine, you can try launching APT from a terminal window. To do this, open a terminal window, change to the directory where the APT.jar is located, and execute the following command:

java -Duser.language=en -Duser.region=US -Xmx1024M -jar APT.jar

The language and region requirements should be set as above (“en” and “US”, respectively), regardless of the global location of the user, in order to ensure correct handling of floating-point numbers with decimal points as opposed to commas. The -Xmx1024M option allocates memory for large images, and can be set to larger values, such as 2048 or 4096, provided that the java command is running a 64-bit Java Virtual Machine. Error messages, if any, will be printed in the terminal window.

This java command can be incorporated into a custom shell script for the routine launching of APT where precise control of the java-command options used to invoke APT is needed. For example, the use may want to create a custom bash script to launch APT. The java command can be further customized by the user to include the pathname to APT.jar, either explicitly or as an environment-variable setting. For example, the following command launches APT with environment variable APT_HOME pointing to the location of the APT.jar file and specifies the -i option with a FITS file to open:

java -Duser.language=en -Duser.region=US -Xmx2048M -jar $APT_HOME/APT.jar -i Level-2-PBCD--IRAC-3.6um.fits

Changing APT’s GUI Size

APT has the option of displaying a slightly smaller-sized GUI. This option may be suitable for laptops with smaller screens. While the default GUI size is 1390 x 835 pixels, the compact GUI size is 1220 x 800 pixels. Using a plain-text editor to change the compactFlag setting to

compactFlag=true

in the default preferences file, which is APT.pref in the hidden directory 

.AperturePhotometryTool

under the user’s home directory, will give the smaller GUI (1220 x 800 pixels).

Alternatively, setting

compactFlag=false
mainGuiSizeX=1000
mainGuiSizeY=700

will give a custom GUI size of 1000 x 700 pixels (the compactFlag must be set to false). This example gives a GUI that is perhaps a little too scrunched, but serves to illustrate how to set a persistent custom size that is dramatically different from the default.

Resizing the GUI with the mouse and saving preferences will store the current GUI size as the mainGuiSizeX and mainGuiSizeY parameters (overwriting the existing values, if any).

Webpage last updated: September 24, 2024 at 8:48 a.m. Pacific Time.