Domains - 52North/IlwisCore GitHub Wiki

Domains attached extra meaning to the raw data that is inside the data-source. It is somewhat similar to a data-type

The pixel values of raster-coverage have no intrinsic meaning. They could be anything. Is it a height value, a reflectance or classified value? By just looking at the value it is difficult to tell. This is true for most of the (raw)data in data-sources. Without some attached metadata or context it is hard to guess the actual meaning of the value. Domains attach this meaning. It is somewhat similar to a data-type but it also has information about allowed values ,units and possibly some more meta-data (depending on the type).

Domains are a seperate Ilwis-object and come in different deravatives (derived from the Domainclass).

• Numeric domains
• Color domains
• Text domain
• Item domains
• Coord domain

Each domain has at least a range of allowed values and a value type.

Domains can form a hierarchical system (optional). This means that a domain may have a parent domain. Though the exact effects of parent domains is particular to the domain type in general it ensures that parent properties are also valid for child domains (unless strict is set, see later).

For example; suppose you have to access a coverage with thematic names of the EUNIS classification. This will create an item-domain , thematic range, a stand-alone domain because the software can’t know that this is a EUNIS classification, it sees a set of names. Comparing this to other coverages using the domains with sets of names that partially overlap is also a bit tricky. Do the names mean the same? Maybe. Metadata is often too limited to make this decision.

By setting the parent domain one ensures that the semantics of domains become the same. It allows for sub-setting of domains without giving up the semantic link between possible disjoint sub-sets. And then there is the strict flag. Again the exact effects are somewhat different for each domain type but in general they limit the power of the parent domain. With the strict flag a value is valid for a domain if it is contained in the range of the domain but the range of the domain must be valid in the parent domain. If the flag is false a value is valid if it is valid within the range of the parent domain. For example. Suppose we have a parent numeric domain with range -1000 … +1000 and resolution 1 and a child domain with 0..100 and resolution 1. With strict set -1 is not a valid value in the child. would while with the strict flag off it would be. 12.47 be invalid in both cases as it doesn’t fall within the range of the parent ( resolution 1). With strictness we retain the notion that domains are compatible but also ensure the integrity of our domain.

Numerical domains are the most common domain in Ilwis. Basically they simply represent floating point numbers and integer numbers. A numerical domain has a numerical range which sets the minimum and maximum for this domain and the resolution which determines how far elements of a numerical domain are separated. The highest resolution (64-bit, double precision) has a resolution of 0. A typical integer domain for example has a minimum/maximum set at some integer values and the resolution at 1.

As such, no time domain exists and yet it is still there. In Ilwis-Objects time as based on the astronomical Julian day ( zero point at noon on January 1, 4713 BC) though the unit in this system is one day, the resolution is 0. A time domain is thus simply a numerical domain with a time-interval as range. Internally it is all doubles. As the range of domain knows it is a time-interval all representations of the values in domain go either to raw numbers or ISO-8601 compatible time strings depending on goal of the programmer.

An item domain is a domain that contains discrete items (duh). The items determine the value type of the domain. Item domains with different value types are not compatible. We have the following value (and thus Item) types

• NamedIdentifier
• IndexedIdentifier
• Thematic
• Numeric
• Time
• Palette color

The differences between the first three are rather subtle. They are all just labels. First of all, identifiers have no attached meaning. They are labels, they identify something. As such, a street sign has no attached meaning apart from the fact that it marks a location. From the name itself you don’t get extra information. The difference between named and indexed easier. Named are unique names (in the domain), indexed are prefixes plus a number.

Thematic items are also labels but they have meaning. Their name implies the value they represent. As such, these items may have metadata associated with them further defining the item. The difference is quite subtle but it has effects. For example, because a thematic item has meaning it makes sense to have a standard (UI) presentation for it. This makes no sense for an identifier item as the name implies nothing. Numeric items are ordered items that have numeric sub-ranges. For example 0-100,100-200,300-400. Time Interval Items are ordered sets of time intervals. For example 20090301-20090311, 20090312-20090322,20090323-20090402. They are very similar to numerical items .

Item domains have a property called “theme”. In a way this is a poor man’s parent domain. In cases where it is not feasible or practical to define a whole parent domain (e.g. insufficient knowledge) one can make item domains compatible by giving them the same theme. At a string based representation level of the items they become comparable but not on the programmatic level below that (see later). What is meant by this? All items in an item domain have a string representation(name). If item domains have the same theme you may assume that names in the domain are pointing to things of the same type/identity. But always remember that this is a shallow equality. The domains don’t have knowledge of each other, their internal representation is different. Only parent domains enforce that also the internal representation is equal.

All child domains have by definition have the same theme.

A color domain attaches a color to an internal value. The color can be pallete based or 3/4 component based color scheme ( e.g RGB or HSL). Some raster coverages dont have 'real' data values but only colors as value (e.g. PNG files). In these cases a color domain is used. The difference between a palette color (in the item domain) and the color domain itself is that the color domain has a continous range between its limits while the pallet colors have only a fixed number of colors.

The text domain is meant for free text. The text is not realy tied to specific elements like for example the labels of an item domain. The text domain has no functional range definition so basically any text is allowed. So why create such a 'pointless' domain? Well. Take for example a table. A table has columns and each column has a data type (domain). The domain of the column limits what is allowed in the column. NumericDomains allows numbers (possibly only within a certain range), thematic domain only allow the labels as values. So what about a column that should contain a textual description? It has no fixed set of values apart from that it has to be text, any text. In cases like this the text domain is used.