ECOCEAN Whale Shark Photo-identification Library Wiki

field_manual_overview_and_purpose

2008-10-13T00:23:05-05:00

Field Manual: Overview

Welcome to the ECOCEAN Whale Shark Photo-identification Library User Community!

Overview of the ECOCEAN Library

The ECOCEAN Whale Shark Photo-identification Library is an Internet-based software application for cooperative whale shark research. The primary purpose of the Library is to increase our understanding of whale sharks on a global and local level and to promote related conservation efforts through high quality research and scholarship. On a purely functional level, the Library is used to collect, protect, store, and share whale shark mark-recapture data gathered from a variety of individuals and institutions worldwide.

A full list of the features of the ECOCEAN Library is available here.

Purpose of this Field Station Manual

The purpose of this field manual is to document the standard operating procedures for the ECOCEAN Library that are required to ensure proper and consistent data collection, processing, and analysis. The intended audience for this document includes:

current ECOCEAN Library users managing whale shark encounter data
prospective Library users seeking to understand how the Library operates
external reviewers seeking an in-depth look at Library operations

For more information about this manual, please contact: info at whaleshark dot org

Next: Managing encounters and sharks

videos - created

2008-10-12T02:30:21-05:00

Field Manual: Tutorial videos

Videos demonstrating the topics covered in this field manual can be found at:

http://www.whaleshark.org/video.jsp?langCode=en#tutorials

home

2008-10-12T02:28:06-05:00

Welcome to the ECOCEAN Whale Shark Photo-identification Library Wiki

This Wiki contains useful documentation for the ECOCEAN Library.

ECOCEAN Library User Documentation

The following documentation provides assistance to ECOCEAN Library users with login access.

Field Manual

1. Overview
2. Managing encounters and sharks
3. Approving or rejecting an encounter
4. Extracting spot patterns
5. Comparing spot patterns with sharkGrid
6. Interpreting pattern match results
7. Matching sharks
8. Searching through the Library
9. FAQs
10. Videos

Other topics
How to use Spot! for perspective correction
TapirLink, the GBIF, and the ECOCEAN Library
List of Photo Keywords (Tags)
List of Location Codes
Features, updates, and maintenance
Known Issues

sharkGrid Documentation

How to Join sharkGrid

ECOCEAN Library Policies

ECOCEAN Library Access Policy
ECOCEAN Library Visitor Agreement
ECOCEAN Library User Agreement

faqs

2008-10-12T02:26:50-05:00

Field Manual: FAQs

1. Why do spots sometimes appear mismapped in the results of a scanTask?

Two things can happen when you see mismapped spots in a scan result.

a. The match results are stored in an XML file. However, the images they pull to map the matched spot pairs to are the latest extraction images. Therefore, when someone remapped the spots, your scan results did not change, but they're now mapped to the new extraction image that was uploaded. The best way to resolve this is:

Delete the old scanTask if it still exists.
Clear your browser cache. (The new Firefox 3 browser works well for this!)
Rerun the scanTask to get the new, corrected results.

b. Flash has a cache for images and patterns. This can also cause a spot mismap if you've looked at a scan result then remapped and rescanned. The second set of results might show the first mapping. In this case, clear your browser cache and then reload the page.

2. Why do some encounters show a "Bad File" thumbnail?

This situation can occur for two reasons:
1. The first submitted image/video is not of a supported image or video file type.
2. A known (but undiagnosed) bug causes some thumbnail images not to be rendered.

Situation 1 can be fixed by logging into the ECOCEAN Library and uploading a supported image/video type OR by asking the webmaster (webmaster at whaleshark dot org)to resolve the bad file (if you don't have required access). If you upload a supported file type, follow the instructions below to regenerate the image thumbnail.

Situation 2 can be remedied through the following instructions:
1. Log into the ECOCEAN Library.
2. Go to the appropriate encounter page.
3. If you have edit permissions for the encounter, look in the Action/Edit bar for the Reset Thumbnail box. Choose the submitted image to generate the thumbnail from and then click Reset Thumbnail.
4. Go back to the page where you first encountered the “BAD FILE” thumbnail and Refresh/Reload the page in your browser.

Next: Videos
Previous: Searching through the Library**

sharkgrid

2008-10-12T02:24:20-05:00

Field Manual: Comparing spot patterns with sharkGrid

The sharkGrid allows connected computers to participate in spot pattern recognition scans run from the ECOCEAN Library. When you start a pattern matching scan for an encounter in the ECOCEAN Library, you are actually creating a scanTask made up of individual comparisons called scanWorkItems. The scanWorkItems of a scanTask are executed in efficient, parallel groups that are distributed across the grid of computers. The results are reassembled once all comparisons are complete. Each encounter can have up to two active scanTasks: one for a left side pattern and another for a right side pattern.

Starting a spot pattern comparison scan on sharkGrid

Once you have extracted a spot pattern for an encounter, you can look for matches to it across a global set of patterns stored in the ECOCEAN Library. To start looking for matches:

1. Select a left-side or right-side radio button from the Find Pattern Match form in the Action/Edit bar. 2. Click Start Scan.

Figure 1. Staring a scan with the Find Pattern Match form

Starting a pattern matching scan creates a new scanTask in sharkGrid. The scanTask is assigned a unique identifier defined as:

“scanL”+encounter number for a left-side scan
“scanR”+encounter number for right-side scan

Note: There can be only one left-side scanTask and one right-side scanTask for an encounter, whether they are completed or uncompleted. If you decide to redo a spot pattern and scan for a match again, you must first delete the old scanTask if it still exists.

You can manage your scanTasks in the sharkGrid Administration page by selecting sharkGrid from the Administer menu (login required).

Examining the results of a scanTask

You can check the status of and view the results of scanTasks from the sharkGrid Administration page.

Pending scanTasks

Pending scanTasks are scanTasks that are:

being created for submission to the grid
being executed on the grid
completed but whose results have not yet been written

Figure 2. Two pending scanTasks in sharkGrid waiting for results to be written

You can delete a pending scanTask by clicking the Delete button.

You can examine the results of a pending scanTask (and move it to “Completed” status) by clicking Write Result. The scanTask will subsequently appear in the Completed scanTasks table.

Completed scanTasks

Completed scanTasks are scanTasks that have been successfully completed in sharkGrid and whose results have been written out for review.

Figure 3. Several completed scanTasks in sharkGrid waiting to be removed

You can delete a completed scanTask that you initiated by clicking the Delete button.

You can examine the results of a completed scanTask by clicking View.

Note: Please promptly delete any completed scanTasks after viewing the results. The latest results can always be reviewed from the relevant encounter page.

Administerng sharkGrid

This section describes how sharkGrid operates and how users with various levels of access can change its behavior.

The sharkGrid queue: Adding and deleting scanTasks

The creation and deletion of scanTasks occurs in a single queue. This means that if several users have simultaneously created new scanTasks or attempted to delete existing ones, these changes will occur one by one. A new create/delete scanTask operation will only start after the previous one in the queue has finished. Therefore, you may not see the results of a scanTask delete (i.e. the removal of the scanTask from the sharkGrid Administration page) immediately.

The number of scanTask additions/deletions in the queue for Administrator-level users is visible in this section of the sharkGrid Administration page:

Figure 4. The scanTask queue in sharkGrid

Viewing connected client nodes and their performance

You can view information about connected client nodes doing work in sharkGrid from this section of the sharkGrid Administration page:

Figure 5. gridManager statistics presenting information about sharkGrid nodes and their efficiency

The following information is available for each node:

IP - the IP address of the node
NodeID - a unique identifier for the node. This identifier is randomly generated.
#CPU - The number of CPUs available for processing on the node computer. sharkGrid will take advantage of multicore CPU architectures and run scanWorkItems in parallel on multicore machines.
Targeted? - whether the client node in working on a specified scanTask or is generally available for processing all scanTasks
# Finished - the number of scanWorkItems (individual pattern comparisons) completed by the node
Chunk size - the number of scanWorkItems sent to the node after each request. All nodes start with one scanWorkItem initially and are given larger workloads with subsequent requests. Ultimately, chunk size is determined according to a pre-defined algorithm in the ECOCEAN Library.

Overall performance in sharkGrid is measured by:

% inefficient collisions - this is the percentage of duplicate work performed by nodes in sharkGrid. The ideal is 0. A collision is detected when a node tries to check in a comparison already completed by another node.
Total work items completed since startup - This is the number of total comparisons performed in sharkGrid since the last restart of the ECOCEAN Library.

Configuring sharkGrid behavior

From the sharkGrid Administration page, you can configure the following performance parameters if you have Administrator privileges:

Set number of allowed nodes - defines the maximum number of client nodes that can participate in sharkGrid
Set node timeout - defines how many milliseconds can pass without a heartbeat from a client node before the node is considered to be no longer connected to sharkGrid
Set checkout timeout - defines how long (in milliseconds) after a scanWorkItem is checked out for processing that it can be checked out by another node. The assumption is that, after this timeout period, the node originally checking out the scanWorkItem has left the grid. A very small value for this may cause inefficient duplication of effort. A very large value may cause a slowdown in overall scanTask processing.
Set number of allowed scanTasks - this is the maximum number of simultaneous scanTasks allowed in sharkGrid. Once the maximum is reached, existing scanTasks must be deleted before new ones are added. Alternatively, the maximum could be increased.
Set maximum chunk/group size sent to nodes - this is the maximum number of comparisons (scanWorkItems) sent to a node after a request. All nodes start at one and advance in group size with each request. Setting this value too high may cause nodes to run out of memory or to take too long processing and register inefficient collisions. A very small value causes nodes to spend more time requesting data than processing it, which is also inefficient.

Video

The following video demonstrates scanning for a match with sharkGrid and analyzing the results.

Links

How to Join sharkGrid

Next: Interpreting pattern match results
Previous: Extracting spot patterns

processing_a_new_encounter

2008-10-12T02:22:23-05:00

Field Manual: Extracting spot patterns

The ECOCEAN Library is a mark-recapture framework for storing and analyzing whale shark data. Among its many features, it supports spot pattern searches to help identify new and previously sighted individual whale sharks using photographs and frame grabs from video.

Basic assumptions

1. For each encounter submitted to the Library, spot patterns can be added for the left and/or right sides if one or both sides have been appropriately photographed. Ideal photographs are taken perpendicular to the spot pattern area, as defined and demonstrated in the red box below.

Figure 1. The area used for spot pattern extraction on the left and right sides is highlighted in red. This photo represents an ideal photograph taken perpendicular to the spot pattern area.

2. To prevent the double-counting of two separate encounters of the same shark as two separate animals (e.g. one encounter submitted with only a left side photo and a second encounter submitted with only a right side photo) only encounters with left side spot patterns that have been extracted and added to the Library can be allocated as new sharks. If they cannot be visually matched to another shark in the Library by other features (scars, etc.), encounters for which only right side spot data can be extracted, must remain “Unassigned” until they can be matched to another shark in the Library.

3. Once an encounter has been assigned to a shark, new spot data cannot be added to it. This prevents the overwriting of existing spot data which was used to identify the encounter previously. To add spot data to an encounter that has been assigned to a shark, the encounter must first become “Unassigned” by removing it from the shark.

Pre-processing a Photo for Pattern Recognition

Any encounter that is not assigned to a shark can have left and/or right side spot data added to it if properly oriented photos were submitted for it. Here are the steps required to extract a pattern from a photo. Let’s use the following photo as a good example.

Figure 2. A new photograph submitted to the ECOCEAN Library.

To ensure that a photograph is properly aligned for spot pattern recognition analysis using either the I3S or Modified Groth algorithms supported by ECOCEAN, it must first be pre-processed in a graphics package. There are a variety of free, inexpensive, and expensive software packages that you can use for the following steps. ECOCEAN uses Adobe Fireworks for simple photo processing or Paint.NET, which is freely available. Other applications, such as Adobe Photoshop and GIMP can also be used. The directions for using your choice of graphics packages will vary. The objective is to obtain a final image of the shark that is correctly-oriented as described in the following sections.

Obtaining a source image from the ECOCEAN Library

1. Login to the Library through a web browser if you have not done so already. 2. In the Library, go to the encounter to which you want to add spot data. 3. In the encounter page, click on the photograph from which you want to extract spot data. 4. Click on the link “Click here to access the original source image.”

Figure 3. Viewing an image and accessing the source file in the ECOCEAN Library.

5. When the original image appears in your browser, right-click the image and select Save Picture As to save the picture to your Desktop.

Pre-processing an image in Paint.NET

If you choose to use Paint.NET to pre-process source images on Windows XP/Vista, use the following instructions. If you use another software program, replicate these basic steps using your tool.

1. Open Paint.NET on your computer. 2. Open the picture in Paint.NET by selecting Open from the File menu.

Figure 4. A whale shark image loaded in Paint.NET.

3. Use the Rectangle Select tool to select the spot pattern area used for whale sharks.
Figure 5. Selecting the spot pattern area in Paint.NET.

4. From the Image menu, select Crop to Selection to reduce the image to only the needed patterning area.
Figure 6. A cropped spot pattern area.

5. We also recommend reducing the size of very large images to ensure the spot pattern area fits neatly onto the Paint.NET canvas at 100% magnification. To adjust image size, use the Rectangle Select tool to select the entire image and then select Resize from the Image menu. Adjust image size appropriately.

6. After obtaining a reduced image of only the spot pattern area, create a new layer to hold a horizontal adjustment line using the Add New Layer button of the Layers pallet.

Figure 7. Adding a new layer to hold a reference line.

7. With the new layer selected in the Layers palette, add a horizontal reference line to the image using the Line\Curve tool . Hold the Shift key when drawing the reference line to ensure it is perfectly horizontal.

Figure 8. Adding a horizontal reference line.

8. Select the Background layer containing the cropped spot patterning area and then use the Rectangle Select tool to select the entire patterning area image. From the Layers menu, select Rotate/Zoom.

Figure 9. Accessing the Rotate tool.

9. Use the Rotate and Pan controls of the Rotate/Zoom dialog box to rotate and move the spot patterning area until the vertebral column is flat against the horizontal line. Click OK when you are done.

Figure 10. Obtaining a proper orientation for the spot patterning area.

Note: The section of the vertebral column just above the fifth gill may curve downward slightly and not fit flush to the line. This is acceptable so long as the rest of the vertebral column above the pectoral fin is parallel to the line.

10. Select the layer with the horizontal red line in the Layers pallet and click the Delete Layer button to remove it.

11. Use the Rectangle Select tool and the Image, Crop to Selection menu command to reduce you image to only the needed spot patterning area.

12. Choose File, Save As to save your completed processed image under a new name.

Figure 11. An image ready for spot pattern extraction.

You are now ready to extract the spots using ECOCEAN Interconnect and send them to the ECOCEAN Library.

Video

The following video demonstrates these instructions.

Sending a pattern to the ECOCEAN Library with the ECOCEAN Interconnect Client

The ECOCEAN Interconnect Client is a small standalone software application that analyzes the image you prepared above and sends spot data to the ECOCEAN Library where it can be used with the I3S and modified Groth algorithms to identify potential matches.

Note: To use Interconnect for the first time, you will need to download it and configure your computer to run it. See Client Software for information on how to obtain and install the free Interconnect client.

To extract a spot pattern and send it to the ECOCEAN Library:

1. Open the ECOCEAN Interconnect Client.

2. From the File menu, select Open left-side shark image.

Figure 12. Opening a new image in ECOCEAN Interconnect.

3. In the Open dialog box, select the pre-processed image file and then click Open.

Note: Only JPG and GIF images are usable at this time in Interconnect.

4. After the image appears in Interconnect, from the File menu select Spot Selection.

Figure 13. Starting spot selection in ECOCEAN Interconnect.

5. Select the three reference points needed for the I3S algorithm (the Modified Groth algorithm does not require these) by left-clicking on the appropriate locations in the image. The red text overlaying the image will prompt you. The order of spots is:

Top of the 5th gill
Posterior point of the pectoral fin on the flank. If the fin is not horizontal, select the point above it where the white countershading underneath meets the pigmented skin along the flank.
Bottom of the 5th gill

To unselect any reference point, right-click it.

Figure 14. Selecting the three reference points needed for the I3S pattern recognition algorithm.

6. Left-click in the image to select the center points of all of the spots in region of interest. To unselect any spot, right-click it.

Figure 15. Selecting spots for computer-assisted photo-identification.

6. After you have selected all of your spots, from the Database menu, click Submit to ECOCEAN Library to send the spot data via the Internet to the ECOCEAN Library. You will need an open Internet connection to perform this step.

Note: Once an encounter is allocated to a shark in the Library, new spot data cannot be submitted for it unless it is removed from the shark to which it belongs. This limitation is designed to preserve spot data used to justify a match and to protect that spot data from accidental overwriting. If you are attempting to add spots to an encounter already assigned to a shark, you must first remove the encounter from the shark to add the spots.

7. In the Send a left\right- side pattern to the ECOCEAN Library dialog box, enter the encounter number in the ECOCEAN Library to assign the pattern to. Click OK when you are ready to send the pattern.

Figure 16. Entering the encounter number to assign the extracted spot pattern to.

8. A new browser window will open to confirm that your spots have been received and prompting you to send in your processed image generated in steps 1-16 above. You may also be prompted to login first.

Figure 17. Uploading the processed image.

9. Browse, select, and submit the processed image in your browser.

10. Your image is now visible (when you are logged in) in the web page for the encounter.

11. Confirm that the appropriate spots have been extracted and mapped using the visual remapping capability in the Library. In the encounter’s web page in the Library, select the link Click here to see the spots mapped to the image, which appears above the image you submitted to see the spots remapped to the image and to confirm their accuracy.

Figure 18. The spot data file itself in the ECOCEAN Library.

Figure 19. Ensuring that submitted spots remap to the original image correctly in the ECOCEAN Library.

Video

The following video demonstrates using Interconnect to map spots and submit them to the ECOCEAN Library.

Next: Comparing spot patterns with sharkGrid
Previous: Approving or rejecting an encounter

approving_an_encounter

2008-10-12T02:17:38-05:00

Field Manual: Approving or rejecting an encounter

The following steps describe how to approve or reject a newly submitted encounter for inclusion in the ECOCEAN Library. Sometimes encounters are added with incomplete or inaccurate information. It is best to leave these encounters as “Unapproved” until the submitter has been contacted and the information has been corrected.

Reviewing a new encounter

To review a new, unapproved encounter for inclusion in the library, follow these steps:

1. Look at the new encounter in the View Unapproved Encounters view (login required) and ensure that the its thumbnail image was correctly rendered. If not, use the Reset thumbnail command on the encounter page to choose a photo to render a new thumbnail from.

2. Check to make sure that all of the photos submitted contain material appropriate for display on the ECOCEAN web site. This is an important check to make sure that offensive material or photos showing inappropriate interaction with whale sharks are not displayed in the library. If the photos contain appropriate content and have enough information (scars, visible left- or right-side patterns in photos, or extractable spot patterns) to reasonably expect that the shark can be re-identified now or in the future, proceed to the next step. If the encounter contains offensive material, no photos, or poor quality photos, proceed to “Rejecting an Encounter” below.

3. Click on each photo one by one to view it in full detail. Note the presence of any distinguishing characteristics, such as scars, distinct spot patterning, or physical tags, using the pulldown list of keywords above each photo.

4. Check and edit the data submitted for each encounter as needed. For example, verify that the size estimate is realistic (30 feet versus 30 meters) and that the submitted comments contain appropriate language and good spelling.

5. Add the appropriate Location Code to the encounter and check any reported GPS coordinates for accuracy using the displayed Google Map.

6. If the content of the unapproved encounter is acceptable, click Approve to make the encounter visible to the general public once all of the above steps have been completed.

7. Check the TapirLink status of the encounter (true/false). The ECOCEAN Library TapirLink policy is available here.

Rejecting an encounter

There are two reasons to reject an encounter:

1. The encounter does not contain enough information to uniquely identify the shark now or in the future, but it does contain some useful data such as date and location, sex, size, etc. that can later be used for trending and aggregate analysis.

2. The encounter contains offensive or inappropriate content. These encounters should be deleted permanently.

To reject an encounter, click the Reject button in the left-hand blue bar of the encounter. This will give you two options:

a. Click Save as DATA-ONLY to preserve this encounter but not make it available to the general public. Note: Rejected DATA-ONLY encounters can be re-approved in the future if enough data is later submitted to allow for a reasonable chance of identification of this animal. As part of the DATA-ONLY rejection process, an email is sent to the encounter submitter informing him/her of the DATA-ONLY status of the encounter and of the insufficiency of data needed for accurate identification. Some submitters may have additional photographs that can be added to each encounter to allow for approval and public display.

b. Click Permanently Delete to remove this encounter from the Library altogether. Note: Deleted encounters can be restored by a Library administrator. If you accidentally select Permanently Delete, email webmaster at whaleshark dot org and reference the encounter number that you deleted to have the encounter restored.

Reaccepting a DATA-ONLY encounter

If you subsequently receive enough data for a DATA-ONLY encounter to allow for possible reidentification in the future, you can reaccept the encounter, moving it out of a DATA-ONLY status.

To reaccept a DATA-ONLY encounter, click Reaccept in the blue bar at the left of a DATA-ONLY encounter (a.k.a. a rejected encounter) to move it back to an Unapproved state.

Next: Extracting spot patterns
Previous: Managing encounters and sharks

Video

The following video demonstrates the concepts covered in this topic.