CS425 Lab: Mac Lab Orientation / Using ImageJ


1. Welcome to the Mac Lab

1.1 First time login

1.2 Account Storage

Your Mac Lab account comes with 4GB of networked storage on mcserver.cs.uregina.ca. Your homefolder is stored there. Any custom desktop settings you make will follow you from computer to compter in the lab. Any files you save to your personal folders, including the Desktop, will also follow you. Any very large files that you will be working with intensely should not be stored on the network, but should be stored on the local computer (see Local Storage).

1.3 Local Storage

Each machine has several gigabytes of available space on the hard drive. You can store files in the folder called /XDATA. Note that Mac OS X is based on BSD Unix and uses Unix file system conventions.

Any files you store on the local machine will only be available on that machine. If you plan to use them on another machine, copy them to a USB drive or your network account.

File permissions on files stored in /XDATA are too permissive - all files are world readable. See the section on Finder/File Management to learn how to secure your data.

1.4 Remote Login

If you need access to your account storage, you can login to mcserver.cs.uregina.ca directly from anywhere in the world with a SCP or SSH client to work with your files.

If you need files that are stored on a specific iMac, you can login to that machine by using its name. Your machine's name is on a barcode sticker on the back of the monitor. You can also list the name of all the iMacs in CL135 from Hercules with this command: cs_clients iMAC.

2. Mac OS X Quickstart

2.1 Desktop Overview

When you first login, your desktop will look like this:

  1. Dock: used for launching programs and organizing frequently used items.
  2. Desktop: used for storing stuff. NOT generally used for shortcuts to applications.
  3. Mac Menu: Log out, System restart and lock screen are here. You can also find information about your Mac. Has a permanent link to the Preferences panel, just in case you accidentally delete it from the dock.
  4. Application Menu Bar: One application, called the front application, is active for user interaction at a time. This application's main menu is displayed here.
  5. Utilities area: You will find controls for Sophos Antivirus, a clock, display settings and volume here, just like the system tray or notification area on the Windows taskbar.
  6. Spotlight: The coolest tool in the utilities area. Helps you find what you need. Just click it and start typing the name of a file or application and watch the results pile in. Click on the best match.

 

2.2 Working with Programs

There are several ways to start programs:

2.2.2 Managing Running Programs

A light colored dot under a program's icon in the dock indicates that the program is running.

There's usually only one command menu in Mac OS X. It is at the top of the screen and it is controlled by the active program. Some crossplatform software, such as MATLAB, breaks this rule.

You can switch between active programs by clicking their icon in the dock, clicking a window that belongs to that program, or by using Command-Tab. That key sequence may seem similar to the Windows Alt-Tab that switches windows, but it is different. It switches Applications. If an application has no windows, or they are all minimized you will switch to it and the only indicator will be the menu bar. If an application has multiple windows and they are not all minimized, you will only switch to the last one you used.

Windows have three buttons in the upper left corner. The red one closes the window, the yellow one minimizes the window, and the green one "zooms" the window. The meaning of "zoom" depends on the program. In iTunes it switches between player and music manager modes. In Safari it selects a window width and height that is large enough to optimally display the current page. In Firefox it maximizes the window as a Windows user would expect.

Mac applications have traditionally had multiple mini-windows with no application container. If you have many applications running with many windows each, the desktop can get very cluttered looking. You can clean it up by hiding other programs. (insert menu entry, key sequence, dock command here)

2.2.3 Stopping Programs

If you want to stop a running program It is not enought to close its windows. The program will stay in memory waiting for you to use it again. Instead you must quit the program in one of three ways:

  1. Switch to the program, click its name in the menu and select quit
  2. Switch to the program and press Command-Q
  3. Right-click on a program and select quit.

 

2.3 The Dock

The dock, located at the bottom of the screen by default, is similar to the Windows taskbar. It provides quick access to the file manager, manages frequently used program icons, collects icons for running programs, provides access to frequently used folders, collects minimized windows, and holds the trash bin.

The dock can be resized by clicking and dragging on the dotted line. Other dock preferences can be set in the preferences panel.

Applications are usually to the left of the dotted line. Minimized windows, folders (especially the trash folder) and files are to the right.

In general things can be added to the dock by dragging them on. Things are removed by dragging them off. Be careful - it is easy for new Mac users to accidentally remove applications when resizing windows or starting programs.

Icons on the dock can be rearranged by dragging them around. As mentioned above, be careful when you do this - if you let go of an icon off the dock it will be removed from the dock.

2.3.1 Remembering Programs

Unless a program is pinned to the dock, its icon will disappear when you exit the program.

To pin a program to the dock, right click on its icon in the dock and select Options | Keep in Dock. If you do this, test the program to see if it behaves properly. If it doesn't you can drag the program's lauch icon to the dock from Finder, which should work everytime.

Don't try dragging programs to your desktop - the program will be moved or copied there which probably isn't what you wanted. There is no way to make a desktop link to most applications because of how the lab is set up.

Try pinning Firefox to the dock. Test it by quitting and restarting Firefox. Some programs are harder to pin to the dock than others. You will use two such programs this semster: MATLAB and ImageJ. You will learn how to pin ImageJ to the dock below. There are similar instructions for pinning MATLAB to the dock in next week's lab.

2.3.2 Forgetting Programs

You can remove programs from the dock similarly. Either right click the icon and select Options | Remove from Dock or drag it off the dock.

 

2.4 User Preferences

In the dock, click the icon with gears on it to access user preferences.

The preferences you set in here will move with you to any desktop in the lab. Some of the settings in the preferences panel are system wide preferences and require an admin password which you don't have. Sorry.

The user preferences panel works a bit like a web browser. Click an icon to enter a preference category. Click Show All to return to the main panel. Click the back button to return to a previous screen.

2.4.1 Fixing Your Mouse

Mac mice have many buttons. Too many. And they are configured strangely by default. Here is how to configure a standard two button setup with scroll wheel:

2.4.2 Changing your Password

2.5 Finder/File Management

Finder is your file manager. Its icon is the two tone face icon in the Dock.

To delete a file either drag it to the Trash on the Dock, or click it and press Command-Delete.

To change the name of a file, click on the file's name and wait a few seconds. Part of the filename will be highlighted indicating that you can change it.

Normally on a Mac you would control file permissions for a file or folder from finder like this:

In the Mac Lab, however, you will have to use the Terminal and the chmod command. Good privacy settings are:

 

2.6 The Terminal

Mac OS X is based on a fork of BSD Unix called Darwin. As such it provides many Unix-like features, including a terminal program. To start it find Terminal in the Utililties folder, or search for Terminal with Spotlight.

Most Macs come configured to run the bash command line interpreter by default, but ours have been configured to use tcsh with similar features to our other Unix environments. The standard Unix plain text editors pico, vi, and emacs are all available to you. You can also make use of g++ and gcc from the command line.

If you plan to make extensive use of the terminal, you may wish to change some of the key bindings or you will likely go crazy trying to use the page-up, page-down, home and end keys. Make the following changes:

 

2.7 XCode

XCode is Apple's application development tool for OS X and iOS devices. It supports C, C++, Objective C and Java type projects. You may want to use it to write code for the class, so here is a quick step by step for setting up a C or C++ project.

2.7.1 Start XCode

You will see a Welcome screen similar to this one:

Although you can choose not to show this window at launch, it is a good idea to leave it there. If you don't the only the only cues you will have that XCode has started are the light under the XCode icon in the dock and, if you haven't switched applications, the menu at the top of the screen.

2.7.2 Create a New Project

The following steps allow you to create a simple C or C++ project for your class assignments.

At this point, you have created a C or C++ project.

2.7.3 The XCode UI

Your project is presented in a single window that has five main regions.

The Xcode Development Window

  1. Toolbar: collects important functions. By far the most important one to you right now is Build and Run. The toolbar is customizable.
  2. Groups and Files List: allows you to explore the various components of your project. Of most importance to you at the moment is the first group, the top group which contains your project's source files. If there are errors simply single click on the error to jump to it.
  3. Detail View: enables you to see the class hierarchies and file folders of the project or solution that you are working on
  4. Editor: where you write and edit your programs.
  5. Status Bar: watch here for messages as you perform tasks such as editing and compiling. You will see a stop sign with an exclamation mark if there were compile errors. You can click it to pop up an error navigation window.
At first the Detail View shows all the files that make up your project. You can narrow this down to code files by clicking on the Source folder in the Groups and Files panel.

New projects have a built in "Hello World" test application. To see the program in action:

By default your program's default working directory (where you load and save files) will be path_to_project_folder/build/Debug/. This may be a bit awkward. If you want, you can set it to your project's folder, next to your source code like this:

You can learn more about XCode and the XCode workflow from Apple by visiting this page.

 

2.8 Common Keyboard Shortcuts

Notice that the Mac keyboard differes from the Windows keyboard:

  1. Instead of Ctrl, Windows, and Alt keys in the lower left there are Control, Option and Command keys.
  2. The Backspace key is called Delete.
  3. The Delete key is called Del and has a funny right arrow with an X in it to show that it is a forward delete key.

Certain keyboard shortcuts are common in Mac OS X native applications. Applications written for X11 are more likely to use Windows-like keystrokes.

Here is a quick list of shortcuts I use often:

Action Shortcut
Cut Command-X
Copy Command-C
Paste Command-V
Save Command-S
Go to next word Option-Right Arrow
Go to previous word Option-Left Arrow
Go to end of line Command-Right Arrow
Go to beginning of line Command-Left Arrow
Go to beginning of document Command-Up Arrow
Go to end of document Command-Down Arrow
Find in document Command-F
Find file with Spotlight Command-Spacebar
Show folder for item in Spotlight Command-Click
Delete File/Item Command-Delete
Switch Application Command-Tab
Switch Window Within Application Command-`
Hide Current Application Command-H
Hide Other Applications Option-Command-H
Close window Command-W
Quit program Command-Q
Zoom in on screen under cursor Control-Scrollwheel
Right click with one button mouse Control-Click
Force Quit Applications Command-Alt-ESC
Quick Log out Command-Shift-Q

There are many more keyboard shortcuts. Lists available on the web include:

3. Using ImageJ

See also chapter 3 in your textbook.

From section 3.2 of your textbook:

"ImageJ... offers a set of ready-made tools for viewing and interactive manipulation of images but can also be extended easily by writing new software components in a 'real' programming language. ImageJ is implemented entirely in Java and is thus largely platform-independent, running without modification under Windows, MacOS, or Linux. Java's dynamic execution model allows new modules ('plugins') to be written as independent pieces of Java code that can be compiled, loaded, and executed 'on the fly' in the running system without the need to even restart ImageJ. This quick turnaround makes ImageJ an ideal platform for developing and testing new image-processing techniques and algorithms. ... [Because ImageJ is free it is] an ideal platform for education and self-training in digital image processing but is also in regular use for serious research and application development at many laboratories around the world, particularly in biological and medical imaging.

"ImageJ was (and still is) developed by Wayne Rasband at the U.S. National Institutes of Health (NIH) [as a replacement for a Macintosh only program]."

In other words, ImageJ is a useful real-world tool that might just work here in the Mac lab.

You can get ImageJ for your computer from the Research Services Branch of the NIH.

3.1 Starting ImageJ

To start ImageJ in the lab

Do not use Right Click | Options | Keep in Dock to pin ImageJ to the dock. Instead drag and drop the icon from /Applications/ImageJ to your dock. In the lab ImageJ uses a custom launch script to set ~/Applications/ImageJ in your home folder as its working directory, and to work around a few quirks of our networked user environment. Because of these customizations, you must drag and drop the icon from /Applications/ImageJ onto your dock or you will cause major problems for other users. See the installation note below.

Installation Note: If you download ImageJ from the NIH, read their instructions for installing and starting it on your system. The Windows version uses an installer and can include Java if you have not installed Java on your computer. The Mac version uses the Java built in to Mac OS X and requires no installation. All versions have the nasty habit of installing your custom plugins to the folder where ImageJ was installed. This means that if you install ImageJ on your Windows PC to C:\Program Files\ImageJ your plugins will be installed in a subdirectory of that path and be available to all users. This also means that for Vista and Windows 7 you must install ImageJ in a folder where you have write permissions.

3.2 Writing and Running ImageJ Plugins

ImageJ plugins are written in Java by using with a custom set of Java classes and implementing certain interfaces. The ImageJ interface that most of the textbook code extends is the PlugInFilter template, which operates on an already open image. You have to implement two member functions to satisfy the template: setup, which is supposed to confirm that your plugin can handle the image type, and run, which is given a class containing the image data for processing. Your filtered result is to replace the original image.

On the Mac, ImageJ does not have an integrated editor. Instead you can use pico, vim, or emacs to write your code. If you wish you may also use XCode as a simple Java editor but it may feel odd because you won't get autocompletion for ImageJ library items. If you are feeling brave you can try following these XCode ImageJ Build Chain Instructions to get a full ImageJ development environment in XCode.

Let's try writing a simple plugin and running it in ImageJ. Remember, in Java filenames must match the public classes they contain or the Java linker gets confused. So a filter implemented as public class My_Filter ... would be saved in My_Filter.java.

Use your favorite editor to input the following code into an appropriately named file:

/**
 * This sample code is made available as part of the book "Digital Image
 * Processing - An Algorithmic Introduction using Java" by Wilhelm Burger
 * and Mark J. Burge, Copyright (C) 2005-2008 Springer-Verlag Berlin, 
 * Heidelberg, New York.
 * Note that this code comes with absolutely no warranty of any kind.
 * See http://www.imagingbook.com for details and licensing conditions.
 * 
 * Date: 2007/11/10
 */

import ij.ImagePlus;
import ij.plugin.filter.PlugInFilter;
import ij.process.ImageProcessor;

public class My_Inverter implements PlugInFilter {

	public int setup(String arg, ImagePlus im) {
		return DOES_8G; // this plugin accepts 8-bit grayscale images 
	}

	public void run(ImageProcessor ip) {
		int w = ip.getWidth();
		int h = ip.getHeight();

		// iterate over all image coordinates
		for (int u = 0; u < w; u++) {
			for (int v = 0; v < h; v++) {
				int p = ip.getPixel(u, v);
				ip.putPixel(u, v, 255-p);
			}
		}
	}

}

To install this plugin:

Note that on the Macs in the lab your plug-ins will be installed to ~/Applications/ImageJ/plugins whereas they will be installed to the plugins folder where you installed ImageJ on all other platforms.

This plugin only works on 8-bit grayscale images. To test it:

3.3 Textbook Resources

You can find all the programs and source images used in the textbook on the textbook's website. They can be downloaded one chapter at a time, or all at once. As of this writing, the link to download all the pictures at once is broken.

 


4. References

  1. Digital Image Processing: An Algorithmic Introduction Using Java, Wilhelm Burger and Mark J. Burge, First Edition, 2008, p. 57