Developers

TLCMap is focused on enabling Humanities researchers to work with digital maps with pathways from beginner to advanced. We also aim to make systems useful for developers to interact with, to extend research further where needed, primarily through RESTful webservices and adherance to common and open standards for interoperability, such as KML, GeoJSON, CSV and ROCrate, at times extending these for required functionality.

Developers of TLCMap systems or systems consuming TLCMap systems should follow these simple but powerful principles to encourage uptake, re-usability, interlinking and usefulness for humanities researchers:

The following, simple but important, easy but powerful, points will enable TLCMap systems and projects to work together as a cohesive whole rather than be a set of disparate research, development and humanities projects. These are all indicated as ‘should’ rather than ‘must’ as the diversity of areas of development means in reality some of these points may not be applicable. While some of these points may seem obvious and desirable and should be standard practice, there are many cases in which they are not implemented so it's worth stipulating.

All TLCMap projects should, where feasible and allowable:

It is important in humanities that any date can be used, and it can be a reason not to use software if it cannot handle any potential date. TLCMap recommends following conventions in the ISO 8601 Date and Time Formats specification XML Schema Part 2: Datatypes Second Edition. This convention is adopted by the KML specification (see Compliance point above).

Times should follow the ISO 8601 format of hh:mm:ss.sss or Thh:mm:ss.sss (with all parts after hh being optional).

A common problem when dealing with dates is the use of different date formats by different countries and by software systems. US dates are often in the format MM/DD/YYYY, with the month at the beginning. A lot of software is developed in the USA so this is sometimes the default setting and assumption. This can lead to a lot of confusion as we move date information around systems, as the 1st of April can easily be changed to the 4th of January without us noticing. It is usually possible to change default software settings to a region with an unambiguous format such as DD/MM/YYYY or YYYY-MM-DD. Because US dates cannot be automatically disambiguated based on their format, TLCMap systems don't make allowances for US dates, unless it is already built in to a system we are using or adding to. Users should convert date formats before data import.

Another common problem is that many databases, and so the software systems built on them, have a 'date' datatype that does not go back very far into the past. They often cannot handle dates with three numbers in the year, such as the 1st of April in the year 786 (786-04-01 or 01/04/786), or BC dates. These problems can be worked around by software developers, by using a text field and adding code for input validation, but it requires effort. Because it is crucial for many humanities projects, in TLCMap software we try to ensure any date can be entered.

TLCMap systems should support several formats of date:

NOTE: For all of these formats a hyphen can be used as a minus sign for BC dates. It must allow for use of 0s to infil, or less that four digits. (eg: 12BC could be -0012 or -12. 10,000BC would be -10000).

KML and GeoJSON

When outputting KML it is recommended to use timespans rather than timestamp elements. Even if you are representing a point in time, set the begin and end to be the same date-time. This allows for expression of vagueness or bounds within with something may have occured. Vagueness is always highlighted by humanities researchers using software that usually expects precision.

GeoJSON and the JSON community has not adopted a convention for describing time in association with place. In many cases, there is a simple requirement for a begin and end date as in the KML timespan element (which can be set the same for a point in time). There are several solutions to this proposed on the internet. TLCMap recommends simply adding a begin and end attribute to the properties is recommended. Eg:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [125.6, 10.1]
  },
  "properties": {
    "name": "Dinagat Islands",
    "begin": "2020-11-01",
    "end": "2020-11-30"
  }
}

Other Temporal Structures

There are many temporal structures that cannot be expressed with a simple begin and end date, and which require unique data structures for storage and communication, and visualisation alternatives to conventional timelines. We anticipate that with continued funding TLCMap will propose conventions for the mark up of these. KML is constrained, but GeoJSON and JSON are flexible enough to allow for these developments.

Temporal structures to be considered are:

Journey

A series of points in a line visited at various dates and times. This is distinct from 'ordinal' time (below), where we describe a series of places that may be visited in order, as on a journey, but not at any particular date or time.

Examples: as a ship visiting different ports at different times, recording it's coordinates at various times in its log. a person travelling around.

Migration

Movements of certain amounts from place to place at different times. This is distinct from a journey in that we are interested in the amount of something moving from place to place over time.

Examples:

How many people migrated from each country in the world through each decade of the 20th century, arriving at which cities?

Frontier

A line or polygon that moves over time.

Examples:

The Western Front in World Wars I and II.

The area being burned by a bushfire.

Stationary

Places that don't move but change in various ways over time. The properties or attributes of things may change in a way that can be visualised, or analysed.

Example:

Over time cinemas in a city are in buildings that don't move, but may open and close, change their ownership, their audience numbers decrease and increase and they might start or stop showing different types of film.

Cyclical

Repeated events which occur at regular intervals. Cyclical time can be quick complex with cycles within cycles and overlapping phases.

Examples:

Festivals and rituals that occur at different seasons or times of the year, or every few years, such as east coast Aboriginal peoples tending to move inland to cooler highlands for hunting in summer and to the coast for fishing in winter, and attending the Bunya festival every three years.

Ordinal

A series of steps that occur in a specific order but not any particular time.

Example:

Instructions to go from one place to another (go down the road to the intersection, turn left until you reach the shop, then go to the end of the bridge near the big tree, etc)

The order in which places are mentioned in a book or set of newspaper articles.

Calendar

Events which occur on a particular date or time.

Examples:

Appointments made in your journal or booking system. Calendaring is probably the most well implimented temporal concept in IT but in humanities we may be also be concerned with complicated issues with alternative calendaring systems, such as the French Republican calendar, or the ancient Mayan calendar.

Space Time Warping

Distance can be thought of not only spatially but temporally, or a combination of both. The distance from one place to another, is sometimes recorded in travel time, rather than kilometres for example. Maps can be 'warped' to visualised distances according to time rather than space. Bear in mind that travelling in one direction may take longer or shorter than travelling back (such as travelling with or against prevailing winds and currents).

Examples:

Medieval itineraries, or travel guides, indicate how long it will take to get to each point on a journey, which is important for provisioning.

Features to get direction in online trip planners usually indicate travel time as well as distance.

Certain kinds of maps such as isochrones can depict travel time by indicating radiating regions or by distorting spatial relations.

The following areas present their own set of technical and theoretical difficulties so can be treated as areas of development and enquiry, though all of the above ways of thinking about time may apply.

Eco-geological

Representing ecological factors or change at the scale of geological time can

Examples:

Representing changing coastlines.

Showing ecological zones that would exist without human habitation, or how they change over millenia.

VR Time

Space and time are fundamental to creators and users of VR, even at the most basic levels, such as the speed at which the user moves. Reconstructing places and objects from history or for heritage are common interests for Humanities VR, and various ways of visualising changes in those things over time presents challenges.

Examples:

Controls for moving around VR environments.

Constructing historical buildings or game environments for people to move through.

A list of data files to use for testing is here.

Also look at the FAQs for other places to discover

If you are a digital humanist or a developer new to mapping technology, here's a few places to start and technologies to be aware of: