iDig

Overview

iDig is a tool for archaeologists. It has been developed and field-tested at the Athenian Agora Excavations of the American School of Classical Studies in Greece (http://agathe.gr).

iDig is designed to produce immediate digital records in the field and is heavily optimized for excavation workflows.

iDig connects wirelessly to Leica Total Stations and keeps excavation data in sync on multiple iPads, allowing for a much higher degree of collaboration during the excavation process.

Scanned drawings and plans can be quickly imported and georeferenced right in the app. Custom fields can be added and excavation records from previous seasons can be imported and connected to the current work for better overall data integration.

Excavation data can be exported in standard UTF–8 tab-delimited format from the built-in web server. Incremental reports can be designed and printed out or saved as simple URL bookmarks. 

Using animation, an excavator can see and track data from a number of useful perspectives: top plan, cross section, and spatial and temporal matrix layouts. Currently iDig supports geospatial searching of the archival excavation data at http://ascsa.net and later versions will allow searching of other excavation archives as well.

iDig contains unpublished data from two trenches excavated in 2013. The formal study of this data will be published in Hesperia, the official journal of the American School of Classical Studies at Athens (http://ascsa.edu.gr).

Training Videos

A training session was held for 4 days during the summer of 2021. These sessions were recorded and can be found here:

Basics

Trenches and Plans

In iDig, items are organized into trenches and trenches are associated with a background plan. You can select the current trench by tapping on the trench title (above the list of items) and you can select the current plan by tapping on the plan title (above the displayed plan).

  Settings

The settings button opens up the settings panel, where trenches and plans can be created and edited.

  Types

The types button allows you to select items of a particular type, such as features, contexts, and objects.

  Status

The status button allows you to select items with a particular status.

  Sort

Press the sort button to toggle sorting the list of items by number or by title.

  Action

The action button provides context-dependent actions you can perform on items, such as copying and pasting items between trenches.

  Layouts

Use the layouts button to select different layouts such as plan and cross section, or double tap on the plan to toggle between the current and previous layouts. Watch the items animate into new configurations when you change layouts.

The following layouts are currently available:

• Plan – a top plan bird’s-eye view of the items
• Relationships – a graph of the relationships between items
• Temporal Matrix – a relationship view showing what is earlier and later
• Spatial Matrix – a relationship view showing what is above and below
• Cross Section – a side view of the items as if cut by a vertical plane
• Index – an icon view of the items

  Pencil

The pencil is a tool for selecting items and drawing cross sections. Tap the pencil button to enable drawing on the screen (the pencil button will turn red when drawing is enabled).

• Draw a circle around items to select them and hide everything else.
• Draw a straight line to create a cross section.

Tip: Circling clockwise will select items that are completely inside the circle. A counter-clockwise circle is less strict and will select anything the circle touches.

Items can be selected from any layout using the pencil. Often it is useful to switch layouts, circle the items you are interested in (the other items will hide), and then switch back to the original layout.

The pencil button turns blue when items are hidden. Double tap a blue pencil to show all items again.

Tip: If an item is blocking your view, hold down on it and drag it off to the side. Any item not in its proper place will be red. Double tap a red item to make it return to where it belongs.

  Start Over

iDig begins with all items visible on a top plan. You can always return to this initial view by tapping the “start over” button in the top left corner of the screen.

Technical Description: The pencil, status, and types buttons function as combination filters. This means that you can select a certain area with the pencil, select certain types of items, select a certain status, and the resulting view will be only those items that meet all filter criteria. (The text search box contributes to the final view as well.) Any button that is actively filtering will turn blue. Tapping the “start over” button simply resets the filters, resulting in all items being displayed on the initial plan layout again.

Georeferencing Plans

iDig uses raster image files for background plans (up to a maximum size of 2048 x 2048 pixels) and assumes a meter-based Cartesian coordinate system.

Tip: To import georeferenced plans, copy the image files and corresponding world files (“.wld” or “.tfw”) into the iDig File Sharing folder via iTunes.

You can georeference new plans inside iDig. Georeferencing will link real-world coordinates with designated locations on a plan.

• Highlight a new plan then select “Georeference plan” from the action button menu.
• Add at least 3 control points by double tapping known locations on the plan for which you have real-world (x,y) meter coordinates. (This typically involves tapping on places where grid lines meet or on fixed points.)
• Edit the values for each control point by tapping on the corresponding (x,y,z) point values. Append the real-world coordinates to each set of values. For example, if the (x,y,z) point values are “156, 116, 0” and the (x,y) real-world coordinates for this point are “539.314 meters west, 452.99 meters north,” then after editing the values, they should read: “156, 116, 0, 539.314, 452.99”.
• Tap the “Georeference Plan” button that appears when you have at least three control points established.

Creating and Editing Items

  Create New Item

Tap the “create new item” button to create a new item and open up the editor.

Here you can select an item type (feature, context, object, etc.), edit fields (title, description, status, etc.), add spatial information (points, lines, and polygons), and establish relationships between items (“is below,” “is after,” “belongs to,” etc.).

Tip: Tap the    “full screen” button to edit an item in a full screen window.

iDig uses the following nomenclature for item types:

• Section – a cross section that represents a specific stratigraphic sequence
• Feature – an entity distinct from its surroundings that usually represents a specific human activity, such as the building of a wall, the paving of a road, or the digging of a pit
• Context – a single stratigraphic unit that has distinguishable physical characteristics and which can be interpreted as functionally or chronologically relevant to the history of the site
• Object – an artifact or natural entity that may be of value in the study of type, style, chronology, or human activity
• Lot – an assemblage of material from one or more contexts representing a single archaeological phase
• Other – benchmarks, measurements, etc.

Each item in iDig has a distinct set of fields: a context, for example, has fields concerned with soil composition and stratigraphy, while an object has fields related to shape and form. You can also add your own custom fields and controlled vocabulary lists to match your own excavation’s recording conventions and nomenclature (see the technical details section for more information on adding custom fields).

Spatial information can be added to items by selecting “add points” and then using one of the following techniques:

• Double tap on the plan to create a “touch point” with (x,y,z) values. Tap on the (x,y,z) numbers to edit them.
• Tap the pencil button and then draw on the plan to create a series of touch points.
• Use a Leica Total Station and capture points wirelessly as they are taken (see the technical details section for setting up the Total Station with a wireless bridge).

Tap the “close polygon” button underneath the list of points to close a series of three or more points into a polygon (a closed polygon is defined as a list of points where the first point is identical to the last point).

Tip: You can adjust the maximum number of coordinate digits that iDig displays before and after a decimal point. In the settings panel under “Show Maximum Digits,” specify the maximum number of digits that you want to display by typing those numbers before and after the decimal point. For example, “5.3” indicates a maximum of five digits before the decimal point and three after.

You can establish Relationships between any two items. iDig currently supports three spatial relationships (is above, is below, is next to), three temporal relationships (is after, is before, is coeval with), and two dependent relationships (belongs to, includes). Tap “add new relation” to create a new relation between items. These relationships are used to create the dynamic matrix layouts.

Tip: Double tapping a relation line will open up the related item.

Special Pencils

Holding down on the pencil button will open a menu from which you can select either the “Camp” or “Talcott” pencil. When you circle an area with one of these pencils, a special geospatial search will be performed.

  Camp’s Pencil

Camp’s pencil will find the lowest items in an area and is useful for connecting current excavation work to previous work.

  Talcott’s Pencil

Talcott’s pencil will find all items in an area and is useful for searching previous excavation work.

Both of these special pencils will crop item boundaries to the selected area. Select “Tidy Up Cropped Items” from the action button menu to reset the item boundaries to their full extents.

Tip: If “Connect to Archive” is enabled in the settings panel, then these pencils will also search the archives at ascsa.net and import any items in the selected area. Select “Tidy Up Archived Items” from the action button menu to clear out these archived items.

Trenchmates

Turn on “Trenchmates” in the settings panel to begin synchronizing with other devices.

Trenchmates provides remote read-only access to other devices. Synchronization with peers is not automatic and all remote changes must be approved by you.

Enter a “Shared Secret” in the settings panel to control access. Only devices using the same shared secret will be able to communicate with each other.

Tip: When Trenchmates is turned on, an http address will be displayed in the settings panel that will allow you to access or export trench data via a web browser. When accessing a device with a shared secret, use the shared secret as the password when prompted.

      Sync with Trenchmates

After turning on Trenchmates, you can begin syncing with peers using the colored ball in the menu bar. Tap the ball to sync with peers on the same wireless network. If the ball turns yellow, then there are data conflicts between you and your peers. Tap the yellow ball to bring up the conflict resolution panel. After all conflicts are resolved, the ball will turn green.

Turn on “Conflict Resolution Suggestions” in the settings panel to pre-select the most recently modified version of an item as the version to keep: you will still be shown all versions and have an opportunity to accept or reject specific changes.

All conflicts should be carefully reviewed. It is possible for an item to be modified simultaneously by multiple peers. The conflict resolution panel will provide you with options for selecting a version to keep or for merging multiple versions together.

Tip: You can quickly copy a trench to another device using Trenchmates: simply create a new empty trench with the same name as the trench you want to copy, then sync with a peer who has that trench and all existing items will be imported.

Backups and Data Safety

Archaeological excavation is inherently a destructive process, and when data is lost, it is difficult if not impossible to recreate. For this reason, iDig has been designed to be extremely paranoid about losing data. Several mechanisms have been implemented in order to make backing up your data easy and losing data difficult.

iDig maintains a “Trash” for each trench. Deleting items from a trench is a two-step process: the items have to be moved to the trash (using the action button) and then the trash has to be emptied.

iDig maintains a “History” folder where trench snapshots are created periodically, providing a seven-day window of backups.

iDig maintains a log of all Total Station points added to a trench, and they can quickly be recovered for a specific item by tapping the action button and selecting “Recover Points” from the menu.

All iDig data is stored in the File Sharing folder that can be accessed via iTunes. This data becomes part of the normal iTunes device backup (which is stored on your computer or in iCloud depending on your iTunes backup preferences). Trenches and plans can also be copied between devices using the shared folder, and backup snapshots can be made by simply copying the contents of the File Sharing folder.

Tip: Using Trenchmates to keep data synchronized between devices is probably the easiest method of maintaining multiple copies of your data (in accord with the LOCKSS principle: Lots Of Copies Keep Stuff Safe: “… but let us save what remains: not by vaults and locks which fence them from the public eye and use, in consigning them to the waste of time, but by such a multiplication of copies, as shall place them beyond the reach of accident.” -Thomas Jefferson, Feb. 18, 1791).

Exporting Data

Trenches can be exported into a simple UTF–8 tab-delimited text file via a web browser (when Trenchmates is enabled). This basic text format can be easily imported into other applications such as Excel, Access, and Filemaker, and can be manipulated with UNIX tools into web-hosted databases such as Postgres and SOLR.

Technical Description: The output format of this tab-delimited file uses the newline character ‘\n’ to separate rows (records) and the tab character ‘\t’ to separate columns (fields). Any newlines and tabs found inside columns will be escaped (e.g. “\\t” and “\\n”). The first line of the file is a list of column (field) names.

Importing Data

iDig will attempt to import any file ending in “.csv” or “.tab” that it finds in the File Sharing folder. Most spreadsheet programs (such as Excel and Numbers) can import and export these comma-separated and tab-delimited file formats. iDig will assume that the field names used in the import file are the same as those used in the export file.

Some care should be taken when importing data. At present, iDig works comfortably with 500–1000 items per trench (depending on the mobile device’s memory capacity). Importing too many records can overload the mobile device. iDig will alert you when the device is running low on memory.

Technical Details

iDig stores all configuration data in the Preferences.json file located in the File Sharing folder. Custom fields and controlled vocabulary lists can be added to this file. The format of this file may change in the future.

For connecting wirelessly to Leica Total Stations, the current implementation uses battery-powered WiSnap RS–232 Serial to Wireless dongles. Total Station system settings should be set at RS–232 output, GSI–16 Mask 2, and communication settings should be set at 9600 baud, 8 bit, no parity, 1 stop bit. iDig listens on the default WiSnap port 55555 for heartbeat packets and uses these packets to identify nearby Total Stations. WiSnap comm settings for open and close messages should be set to zero (e.g. “set comm close 0” and “set comm open 0”).

Privacy Policy

iDig does not collect any personal information about you.

Acknowledgments

Created by Bruce Hartzler and Georgios Verigakis. Special thanks goes out to the field supervisors, assistants, and diggers at the Athenian Agora Excavations who have provided valuable testing and feedback, especially Mike Laughy, Matt Baumann, James Artz, Laura Gawlinski, Brian Martens, Nicholas Seetin, Marcie Handler, Daniele Pirisino, and Johanna Hobratschk. To Thierry Theurillat, a programmer's dream beta-tester. To Anne Hooton for creating the application icon and color palettes. To Molly Richardson, the best editor in the world. And to John Camp, the excavation director, for his constant and enthusiastic support of this project.