1

USER’S MANUAL OF CEmin Earth Observatory of Singapore, Nanyang Technological University

November, 2017

USER'S MANUAL

TABLE OF CONTENTS

1 GENERAL INFORMATION .................................................................................................... Page 2

2 BASIC FUNCTIONS ................................................................................................................. Page 2

2.1 Installation ...................................................................................................................... Page 2

2.2 Getting Started ................................................................................................................ Page 3 2.3 Grayscale View Function ................................................................................................. Page 3

3 DATA PROCESS SUBPANEL ................................................................................................. Page 5

3.1 Voids Utility ..................................................................................................................... Page 5

3.2 Outiline Utility ................................................................................................................. Page 6 3.3 Repair Utility .................................................................................................................... Page 7 3.4 Extract Utility ................................................................................................................. Page 13

4 DATA STATISTICS SUBPANEL .......................................................................................... Page 14

4.1 Parameter Calibration Utility ......................................................................................... Page 14 4.2 Distribution Statistics Utility .......................................................................................... Page 15

5 DATA COMBINATION SUBPANEL .................................................................................... Page 17

5.1 Operation Flow of Data Combination ............................................................................ Page 17 5.2 Example of Data Combination ....................................................................................... Page 17 5.3 Read Combination Result ............................................................................................... Page 20

6 SOFTWARE AND USER MANUAL DOWNLOAD LINK ..................................................... Page 22

2

1 GENERAL INFORMATION • CEmin has both MAC version and windows version. This user manual is available for

the two versions.

• CEmin is developed by Ling Zeng, and it is supported by the National Research Foundation of Singapore and the Singapore Ministry of Education under the Research Centres of Excellence initiative, under the “Crystal pattern” project.

• There is a corresponding paper for CEmin that illustrate the underlying principles to run CEmin: CEmin: A MATLAB-based software for computational phenocryst extraction and statistical petrology.

2 BASIC FUNCTIONS

2.1 Installation • The user can download the installation files of CEmin by the link

http://www.earthobservatory.sg/resources-solr?f%5B0%5D=field_resource_type%3A86. There are installation files respectively for windows and Mac.

• Before opening the application of CEmin, the user should make sure that there is a corresponding MATLAB version on the operation system. For windows, it’s Matlab R2017b, and for Mac, it’s Matlab R2014b. If there is, the user can directly open the application of CEmin.

• Or else, in the installation files there is the corresponding Matlab Runtime version respectively for windows and Mac that can help to run CEmin. The user should firstly install the corresponding Matlab Runtime and then can open the application of CEmin. This is an example to install MATLAB Runtime in Mac:

Open folder “MCR_R2014b_maci64_installer” to find the application “InstallForMacOSX” and run it. Before running it, make sure to set “Open Anyway” for “InstallForMacOSX” in the “Security & Privacy”.

After opening InstallForMacOSX, please “Next” to agree the license and choose an installation folder to create and install it. After completing installation, the user can get started with CEmin.

• The application of Matlab Runtime for windows is “MCR_R2017b_win64_installer”

that is different from Mac, and the user can run this application as follow:

3

Select “Next” to agree the license and choose an installation folder to create and install it.

Wait to complete installation, and then the user can get started with CEmin. 2.2 Getting Started

• After downloading the CEmin folder, start the program CEmin by double clicking the

CEmin icon in the CEmin folder (Fig. 1a). The Control Panel will open (Fig. 1b). If the user encounters an error message “error that the runtime 9.3 was missing”, the user can try right clicking on CE.exe and selecting ‘run as administrator’.

• Menu Bar of the Control Panel: “Open”, “Save to” and “Exit” comprise the menu bar of the control panel interface (Fig 1b).

“Open” is used to open a backscattered electron (BSE) image for processing. Four formats (“.jpg”, “.tif”, “.jpeg”, “.png”) can be opened by CEmin.

“Save to” allows the user to choose a folder in which to save text and image data during the “Data Process”, “Data Statistics”, and “Data Combination” steps. The folder may be chosen in the beginning or during later processing steps. The designated folder may be changed if the user would like to save different data in separate folders.

“Exit” is used to close all of CEmin, including the control panels and view windows.

• Opening an image automatically launches the View Window with the image (Fig. 1c).

Fig.1 (a) there are three files for CEmin: “cemin” (outlined in red) is the launch icon of CEmin and the other two are the support files for running cemin. (b) Control Panel of CEmin, which is launched by

4

double clicking the “cemin” icon. (c) View Window of image opened by clicking “Open” in the menu bar and then selecting an image file.

2.3 Grayscale View Function

The Grayscale dropdown menu in the View Window menu bar has two tools (Fig. 1c): • Areascale tool is used to determine the mean grayscale value within a region of

interest, or the grayscale of a spot. To access, click “Areascale”, then move the cursor to draw a rectangle over the area of interest. A message box will immediately appear reporting the Mean-Grayscale (the average grayscale value of the pixels in this area) and the total number of pixels within the selected area (Fig. 2).

• Linescale tool is used to determine the number of pixels along a horizontal feature of known length. To access, click “Linescale”, then move the mouse to draw a horizontal line on the image. A message box will appear showing how many pixels correspond to the length of line. If the line is not horizontal, the message box will remind the user to make the line horizontal (Fig. 3).

Fig. 2. The Areascale tool can be used to help check the “Threshold” values of both voids and crystals during the “Data Process” step. This tool is also used to help calibrate grayscale to chemistries (composition) when using the An Calibration function. The region of interest selected by the Areascale tool is rectangular or a point.

5

Fig. 3 The Linescale tool is used to calibrate image scale when using the Scale Image function in the Data Statistics subpanel. The Linescale tool requires a nearly horizontal line.

Fig. 4 Delete selected regions of interest or lines using “Delete” under the right click menu

3 DATA PROCESS SUBFUNCTION

3.1 Voids Utility

Voids utility is aimed to remove voids by firstly selecting Nums and Threshold input parameters. Generally speaking, the values of the Nums and Threshold input parameters

6

for voids are not sole and can vary a bit within some range that will not affect the resultant image of the geometries of crystals’ outline. • Input parameters

The Threshold value of voids is at least the maximum grayscale of those black areas and must be less than the minimum grayscale of crystals that will be extraced. The default value of Threshold of voids is roughly 0 to 10 if the average grayscale of voids is around 1 or 0 as shown in Fig 5 and 6. Alternatively, the user may also use the Grayscale -> Areascale tool to check the grayscale values of voids.

The Nums value of voids is theoretically the number of black areas with similar sizes as the crystals of interest, as well as those easily misidentified as extra parts of crystal edges. The voids Nums value is empirical, and the user can estimate an initial number and inspect the resultant image, adjusting the Nums input parameter until satisfied. In the example provided in Fig 7, with a Threshold of 0, a Nums value of 40 offers the best result.

• Remove Function

The function of removing voids can be executed by the button “Remove”, just after filling all input parameters of voids.

3.2 Outline Utility

Outlining crystals’ geometries is firstly based on the results of removing voids or using the set of parameters of voids determined above (Voids Threshold = 0 and Voids Nums = 40.; Fig. 7c), then determining the Outline input parameters values, and finally executing Outline Function for crystals’ geometries. • Input Parameters of the Outline utility

The Outline Threshold value: we set the initial Outline Threshold value to 120 (Fig. 8) by using the highest grayscale value of some bright spots of crystals determined in Fig. 2. From the comparison of six resultant images of outlines in Fig. 8, we may see that if Outline Threshold value is too low (as Fig. 8 a and c) a lot of the area of the crystals of interest are excluded. Conversely, if the Outline Threshold is too high there are other brighter crystals and matrix minerals are included (Fig. 8 e and f). In this case, an Outline Threshold value of 140 or 160 (Fig. 8 b and d) is appropriate, with 160 offering a slightly better result.

The Outline Nums value (the number of outlined crystals): the user may try to get the satisfactory value iteratively, since the ideal value is not unique to each image.

Dilate_sz value ranges from values of about 5 to 20. The user should also determine the ideal value iteratively.

• Outline Function

7

The function of outlining crystals’ geometries can be executed by the button “Outline”, just after filling all input parameters related to crystals.

3.3 Repair Utility This utility is used to perfect crystal geometries. • LineSize

The input parameter “LineSize” is to sets the line width of Repair utility in pixels.

When using the Separate and Enclose functions to separate connected crystals and enclose the edges of individual crystals, LineSize generally ranges between 50% and 70% of Dilate_sz.

When using the Erase function to get rid of extra parts of crystals or some scattered crystals, it will depend on the specific objects and user will become familiar with setting the appropriate LineSize with use.

For the Fill function, setting LineSize is not necessary.

• Separate

Firstly, set the LineSize value to approximately 5, then click “Separate”.

Move the cursor on the outlined image to where you want to separate connected crystals (Fig. 10a and b).

Left click at the desired starting point, then move the cursor to the desired end point and double left click. The resultant line should separate the connected crystals.

• Enclose

Keep the value of LineSize at approximately 5, then click “Enclose”

Place cursor at one edge of the crystal embayment that you wish to enclose and left click to initiate a line segment (Fig. 10b and c). Additional single clicks will create any number of desired intermediate points along the enclosed path, and a double click will terminate the line path at the opposite edge of the embayment to be enclosed.

• Fill

After performing the Enclose function, click Fill function to the fill the empty spaces inside the crystals (Fig. 10c and d).

• Erase

Set the LineSize to approximately 10.

8

Move the cursor to cover the areas you wish to erase. Holding the left mouse button and moving the cursor will erase the desired features, just as an eraser tool (Fig. 10d).

Fig. 5. Resultant images after removing voids. Here we keep the value of the Nums of voids constant and adjust only the Threshold of voids parameter. (a) Threshold = 0, as indicated in Fig.3, the edges of voids have not been removed completely. (b) Threshold = 10, the resultant image is satisfactory. (c) Threshold = 30, resulting in excessive removal, especially along cracks and other areas within target crystals, that will require repair.

9

Fig. 6. Images produced by performing Outline function based on the Fig.5. These examples demonstrate how changing the Voids Threshold input parameter affects the resultant outlines of crystals. Crystals in (a) and (b) are reasonably well outlined, while in (c) too much area has been removed from crystal margins and interiors. Generally, the Threshold value should be set to the average grayscale value of the voids.

10

Fig 7. Images showing the influence of Nums of Voids parameter on removing voids and outlining crystals. (a) Several voids (circled in red) are not removed and become extra parts of crystals or connections to other crystals. (b) Relatively obvious voids (in red) have been removed and only some small voids become extra parts of crystal edges. (c) Most smaller voids have been removed. In general, (b) and (c) are fine, however, (a) can also be repaired by erasing obvious voids attached to the edges of crystals.

11

Fig. 8. Images showing the influence of the Outline Threshold parameter on removing voids and outlining crystals. (a) When Threshold is 120, the resultant image of crystal outlines contains many empty areas inside crystals. (b) When Threshold is 140, the empty areas are fewer. (c) When Threshold is 100, more empty areas are present than when it is 120. (d) When Threshold is 160, fewer empty areas are present than when it is 140, and this is close to ideal. (e) When Threshold is 190, there are some extra parts attached to crystals and many crystals are connected. (f) When Threshold is 220, there are other kinds of crystals and a lot of matrix included.

12

Fig. 9 Images showing the influence of the Dilate_sz input parameter, which mainly affects the edges of crystals. If it is too high, the edges of crystals will appear “bitten into”. If the value is too low, crystal edges will have extraneous spurs. In this example, when Dilate_sz is set to approximately 10-15, the resultant crystal outlines are most accurate.

13

Fig. 10. Flow of the repair process.

3.4 Extract Utility • Once the outline of crystals is satisfactory, with or without repairs, the user may

extract crystals by two ways:

Extract all crystal geometries and grayscales and into one image using the “as.All” Function button.

Extract individual crystals as different image files using the “as.Single” Function button.

Before selecting “as.All” or “as.Single”, the user must first use “Save to” in the menu bar of the Control Panel (Fig. 1b) to select a folder for the extracted images to be saved to. The selected folder will serve as the default location for all exported data, until a new folder is selected. As shown in Fig. 11, left click the designated folder, and then click the Open button on the bottom right.

14

Fig. 11 choose a designated folder to save data and images.

4 DATA STATISTICS SUBPANEL

4.1 Parameter Calibration Utility This utility is prerequisite for using the Distribution Statistics utility discussed below. • Actually, the Scale_Image function is the shortcut to get a new original image

window so that the user can use Linescale tool in the Grayscale view function (described in chapter 1) is used to scale a feature of known length in the image to its actual length in micrometres (Fig. 3):

After clicking on the “Scale_Image” button, a new Image Window will appear along with a message box to remind the user to use the Linescale tool.

The user can perform the Linescale tool image scaling, as previously described, and input the resultant Pixels and Microns values in the corresponding fields (Fig. 13).

• The An Calibration function converts grayscale values to Anorthite contents:

After clicking on the An Calibration button, an input dialog will appear.

Input the pairs of anorthite and grayscale values based on EPMA data (Fig. 12a). The user can select locations of known composition using the “Areascale” tool, which will provide the mean grayscale value of the selected area. Alternatively, the user also may use “ImageJ” to get the grayscale values of the areas that already have EPMA data of anorthite content.

Click the Calculate button, and the regression parameters will be shown in the plot (Fig. 12b), along with the error expressed both as the correlation coefficient R and the mean absolute error in An.

15

Input the resultant Slope and Intercept parameters in the corresponding fields (Fig. 13). Note that realistic values must be input for anorthite content in order to generate a meaningful regression. A regression that generates negative An values within the grayscale range can cause errors.

Fig 12 the An Calibration tool. (a) is the input dialog. After inputing the values of anorthite and their corresponding grayscales, press Calculate and the plot (b) with the regression parameters will appear.

Fig. 13 Input all parameters for Data Statistics

4.2 Distribution Statistics Utility

Distribution statistics here include statistics of grayscale distributions, chemical distributions and area distribution. These distribution maps are saved either as text format or picture format. Because of the previous steps completed in CEmin, the user simply clicks these buttons, and all data will be directly saved to the folder that is designated previously. The user may change the “Save to” folder just before clicking the Distribution Statistics buttons. • Read Grayscale and Chemistries distributions:

Grayscale distribution maps (Fig. 14a) show that the geometry of the plagioclase crystal extracted (here, e.g. the first plagioclase crystal) and its grayscale distribution map (in the upper panel), and the geometries of all plagioclase crystals extracted and their grayscale distribution map (in the lower panel). The

16

x-axis is the grayscale levels from 0 to 255, and the y-axis is the areas in square micrometres across all grayscale levels. The distribution texts are almost the interpretation of the distribution maps, and the sole difference is that in the distribution texts, CEmin also calculates the area percent of each grayscale level across the whole grayscale levels.

Chemistries distribution maps (Fig. 14b) show the geometry of the plagioclase crystal extracted (here, e.g. the first plagioclase crystal) and its anorthite distribution map (in the upper panel), and the geometries of all plagioclase crystals extracted and their anorthite distribution map (in the lower panel). The x axis is the anorthite content level from 0 to 100, and the y-axis is the area in square micrometres across all anorthite levels (0 to 100). And the distribution texts are almost the interpretation of the distribution maps, and the sole difference is that in the distribution texts, CEmin also calculates the area percent of each anorthite level across the all anorthite levels.

Fig. 14 (a) plagioclases grayscale distributions; (b) plagioclases chemistries distributions

• Read Area distribution – Fig 15 shows the area distribution of plagioclases as a

histogram.

In the distribution map, the x-axis is the real area in square micrometres, and the y-axis is the numbers of plagioclases. For example, the highest bar indicates that there are 7 plagioclases whose areas range between ~0.5 × 105 and 1 × 105 square micrometres.

In this case the distribution text is a bit different from the distribution map. Here, CEmin names individual plagioclases according to their size. For example, in the “No. Series_plag” column (Fig. 15), 1 refers to the plagioclase crystals with size ranking No. 1, and 18 refers to plagioclase crystals with size ranking No. 18. “All

17

plags” gives the statistics for all plagioclase crystals extracted (here, there are 18 plagioclases in total), and “this image” gives the statistics of area across the entire BSE image. In the area (microns^2) column, CEmin calculates the area of the whole BSE image, the total area of all plagioclases, and the area of each plagioclase. In the area_vs_image(%) column, CEmin calculates the area percent of each plagioclase crystal out of the whole image and the area percent of all plagioclases out of the whole image. In the column of area_vs_allplags (%), CEmin calculates the area percent of each plagioclase crystal out of all plagioclases.

Fig. 15 area distribution statistics

5 DATA COMBINATION SUBPANEL

5.1 Operation flow of Data Combination • Data Combination is used to merge data from different images. In the previous step

of Distribution Statistics, we were able to export data for individual crystals, or for all crystals within a given image. In Data Combination, we can create a combined dataset for multiple images. We can combine data for each of the five data export operations in Data Statistics:

Gray.all is used to merge the grayscale distributions of all plagioclases from different images.

Gray.single is to merge the grayscale distributions of individual plagioclases from different images.

Chem.all is to merge the anorthite distributions of all plagioclases from different images

Chem.single is to merge the anorthite distributions of all plagioclases from different images.

Area is to merge the area distributions of all plagioclases from different images.

• Before running Data Combination, the user should make sure that there is already a

designated folder to save all resultant texts from combination. Here, in our example,

18

we created a folder named “comb_results” (Fig 18) and designated it as the export location using the “Save to” option in the menu bar of the Control Panel.

5.2 Example of Data Combination • Fig 16a shows two sample thin section images, and both are from Mayon volcano,

located in the Philippines. The Distribution Statistics utility has already been used to create data files for all possible data outputs (Fig 16b): chemistries distributions for individual plagioclase crystals and all plagioclase crystals, grayscale distributions for individual plagioclase crystals and all plagioclase crystals, and area distributions (in total five data types).

• We sort five data types from both images into five individual folders, as shown in Fig 17:

Chemistries distribution data files for all plagioclases from “volcano” and “1947-1_plg” are put in the “com_chem.all” folder.

Chemistries distribution data files for individual plagioclases from “volcano” and “1947-1_plg” are put in the “com_chem.single” folder.

Grayscale distribution data files for all plagioclases from “volcano” and “1947-1_plg” are put in the “com_gray.all” folder.

Grayscale distribution data files for individual plagioclases from “volcano” and “1947-1_plg” are put in the “com_gray.single” folder.

Area distribution data files for plagioclases from “volcano” and “1947-1_plg” are put in the “com_area” folder.

• To merge data from the two images, click on the desired data type to merge (Gray.all,

Gray.single, Chem.all, Chem.single, or Area), then select the corresponding folder where the corresponding data files are located. The combined result will be saved to the designated folder (Fig 18).

19

Fig 16 (a) Extracted plagioclase crystals from the images “volcano” (upper image) and “1947- 1_plg” (lower image). (b) Statistical distribution data files from the two images, originally stored in two separate folders.

Fig 17. Sort data files into separate folders according to data type prior to using Data Combination.

20

Fig 18. Combined data files produced by Data Combination, corresponding to Figs 16 and 17, saved to the folder “com_results”.

5.3 Read Combination Results

Generally, if combining grayscale distributions from different images, the brightness and contrast settings of the BSE images should be constant, as should any other relevant microscope and sample parameters. Figs 19 and 20 show examples of combined datasets.

• The combined grayscale and chemistries distribution data respectively by “Gray.all” and “Chem.all” are shown respectively in Fig 19a and b, for all plagioclases in both images. The first column is either the grayscale level (Fig 19a) or anorthite content (Fig 19b). The second column is the area in square micrometres of each grayscale level or anothite content level. The third column is the area percent of each grayscale level or anorthite content level.

• The combined area distribution data by “Area” (Fig 19c) show the area in square micrometres of each plagioclase crystal from the two images (area_microns^2), the area percent of each plagioclase crystal and all plagioclase crystals out of the combined area of the two images (area_vs_image(%)), and the area percent of each plagioclase out of the total area of all plagioclase crystals of the two images (area_vs_allplags(%)).

• The Gray.single and Chem.single functions combine grayscale and chemisties distribution datasets for each crystal in each of the combined images. In Fig 20a, CEmin has calculated the area in square micrometres of each grayscale level (0-255) for each plagioclase crystal from the two images and their corresponding percent out of the total area of all plagioclase crystals from the two images. In Fig 20b, CEmin has calculated the area in square micrometres of each anorthite content (0-100) for each plagioclase crystal from the two images and their corresponding percent out of the total area of all plagioclase crystals from the two images.

21

Fig 19 Combined datasets from the two images in the example provided in Figs 16-18. (a) Grayscale distributions for all plagioclases. (b) Anorthite content of all plagioclases. (c) Area distributions for all plagioclases

22

Fig 20 (a) Combined grayscale distributions for each individual plagioclase crystal from both of the images combined in the example provided in Figs 16-19. (b) Compositional distribution for each individual plagioclase crystal from both of the images.

6 SOFTWARE AND USER MANUAL DOWNLOAD LINK Mac and Windows versions of CEmin software, as well as a user manual, are freely available to any interested researchers at the following link: http://www.earthobservatory.sg/resources-solr?f%5B0%5D=field_resource_type%3A86

23

This file repository is hosted by the Earth Observatory of Singapore, and links to several other published geological software packages can also be found there. All are available free of charge, as part of Earth Observatory of Singapore’s continued commitment to the research community. Software updates will be added to this folder as they are developed.