Introducing Djinn

Introduction to the Djinn Project Report

This is a draft version of the 'non-mathematical' Introduction to the Djinn Project Report (Part I, Chapter 1B). Some small changes have been made to render it free-standing.

This chapter starts with a description of the philosophy underlying the design of the Djinn API, followed by a summary of the requirements considered in the design. The last part of the chapter briefly introduces the concepts used at the interface. (A more formal mathematical definition of these concepts is given in the following Chapter.)

Philosophy

Djinn and the application

It is assumed that some major piece of software, known in this book as the application, is using a library of geometric functions, called Djinn, to build geometric objects, to carry out geometric operations on them, and to enquire about their geometric properties. It is necessary to distinguish carefully between the definition of the geometric functions, called the Djinn API, and the underpinning executable code, which will be referred to as the Djinn implementation.

The application is normally expected to be a non-trivial piece of software, possibly many times the size of the Djinn implementation, written by competent programmers. The latter assumption implies that it is not necessary to provide every possible facility within Djinn. Thus the main concern in the design of Djinn has been to ensure that the facilities which the application actually requires can be realized by appropriate programming, using the API. Indeed several aspects of the Djinn API are influenced by a guiding principle of minimality, including considerations such as:

The exposure at the API of only the minimum number of concepts necessary to support all of the intended functionality.
The number of interface functions is kept to the minimum possible without recourse to so-called gateway procedures and switches.

Following the first of these considerations, the Djinn API design exploits, as far as practical, ideas of encapsulation (data hiding) and generalization recently popularized in object-oriented programming environments.

A particular instance of the application of minimality is the lack of 'logging' or 'journalling' facilities in the Djinn API. As far as the application is concerned, Djinn functions are atomic, indivisible operations and thus the calling program can easily log calls to them. A log file maintained by the application can also contain data relevant to other important stages in its operation rendering simple logging of function invocations at the Djinn API rather less useful by comparison. Furthermore, it seems counterproductive to encumber the Djinn API with generic functions for logging which are likely to be already available to applications in any general programming environment.

The Djinn API has also been designed with the expectation that the application will have significant data structures in its own right. Provision has been made for associations to be created and maintained between application data and that hidden inside the objects maintained by Djinn.

Having said all this, however, the minimality principle is a weak one in that, where the provision of a function which is not strictly needed would give significant convenience, it is included in the API

Representation-independence

It is taken as axiomatic that the application programmer using a modelling API such as Djinn is concerned with the functions provided and their efficiency, and not with the internal representation of geometry or the particular algorithms used. It is therefore necessary that the Djinn API must be defined in abstract terms that are not specific to any of the modelling paradigms that may be used by the underpinning implementations (which may be boundary, set-theoretic, oct-tree or faceted representations as already stated). In other words, an 'open' geometric modelling kernel API must be representation-independent.

In the Djinn API, representation-independence is achieved by couching definitions in terms of point-sets and operations on them, as will be explained in more detail later in this chapter. By this device, applications can manipulate geometric abstractions rather than boundary graphs, set-expressions or any other structure specific to a particular modelling paradigm. Thus neither the underlying modelling paradigm used nor any particular language implementation is reflected in the API definition, but issues of accuracy, degeneracy, robustness and exception handling are dealt with explicitly. Indeed, implementations are free to use multiple representations and to employ conversions internally if necessary; the Djinn API only defines what is to be computed without reflecting how it should be done. In designing Djinn, however, consideration has been given to 'implementability'; it would be foolish, for example, to build in the assumption of the existence of a general solution to the historic problem of converting models from boundary to set-theoretic representation.

State and side effects

In designing any API, it is important to decide whether the implementation behind it will maintain any information about its internal state between function invocations across the interface. In the case of Djinn, it is clear that the geometric objects handled by the implementation contain state to record their shape, and possibly other related information. However, an important Djinn design aim has been to make this state (and its limitations) extremely clear.

It has been decided that all Djinn functions are to be re-entrant, so that all manipulations of different pieces of geometry can be interleaved (or even concurrent, if the implementation permits that) without interaction. This means that there is no state in Djinn outside the data objects which are passed in and out of the functions as arguments. One practical result of this, for example, is that a desired computational accuracy has to be supplied to each interrogation function rather the Djinn implementation keeping any 'accuracy state' information. The only exceptions are an indication that Djinn has been correctly initialized, and other data relating to the reading and writing of information to files for persistence or archiving purposes. Writing an object to a file does have a side-effect on the file, and reading an object does alter the position of the 'read-pointer' within it. This exception has to be accepted, as to have outlawed it would have prevented any data from lasting for more than one 'session'.

Persistence