In this section we describe the structure of a model and the organization of data within the DGD Gallery. It is also explained how users create, edit, and interact with models using model permissions. Finally, we give details on the submission system and the review process.
4.1 What Is a Model?
The architecture of the DGD Gallery is built around the definition of the Model, see Fig. 6. The teletype font is used to indicate that a word is the name of an abstract data type, one of its attributes, or an admissible value. From a high level perspective a model is a collection of files together with a description. The description contains fields for the title, authors, a description text, keywords, literature references, and the creation date. The data files associated with a model are bundled into media objects. A media object is a set of files together with a title and a description text. These files may be images, videos or data for specific software systems. While some file formats are more common (and more reasonable) than others, conceptually we allow for any file format to become part of a media object. In this way our design is very flexible and thus could be applied in other contexts.
The data type Model has a key, a version number, a status field, and an edited-by username. The model key is a unique identifier that is used, e.g., to assemble the permanent link of the model on the web. The version number is assigned automatically for keeping track of a model’s history. Throughout the following the word “model” refers both to a specific version and to the entire history of a model. The standard representative of a model is given by its latest version. The edited-by field contains the username of the author of a particular model version. Hence, in a database a model can be uniquely identified by its key, a model version is identified by its key and version number.
The status of a model can take the values edit, pending, rejected, or approved. See Sect. 4.5 for a detailed description of the model status and the submission process for models in the gallery.
The model description is a collection of the following information that is provided by the editor of a model. While this somehow resembles the structure of a traditional research paper, there are some notable differences.
-
The Title of the model.
-
A sorted list of Authors. Since this is a frequent source of misunderstanding, it is worth explaining. The authors of the model are those who create the content that is presented online. Like for a research paper all the scientific work that leads to the model must be properly acknowledged in the references. However, clearly, the set of authors cannot comprise all the authors who contributed something to the entire history of a mathematical idea. For instance, suppose that Alice first describes a new type of surface in a traditional research paper, and Bob afterwards produces a model from Alices description (without Alice’s help). Then Bob is the only author, who must cite Alice’s paper.
-
The description Text, which can contain any valid LaTeX source code that can be compiled using the MathJax library, see [27]. References to the literature or to media objects can be cited via the \cite{.} command. Previews of media objects can be included with the \media{.} command.
-
A set of keywords can be assigned to the model. The keywords are used on the web-site to, e.g., improve search features.
-
A set of references each of which consitsts of a reference key that is to be used in \cite commands and a set of key value pairs. The user interface of the gallery maps Bib
\({\text {T}_{\text {E}}}\)X entries to model references. Conversely a model reference is rendered and referenced using common Bib
\({\text {T}_{\text {E}}}\)X styles.
-
The date field of the description contains the creation date of the particular version of the model.
A model contains a number of media objects for visualization and use in other software systems. This concept will be explained below.
4.2 Media Objects and Data Files
A media object is a collection of files that describe the same set of data associated with the model. For instance, several media objects might correspond to various views of the same model; e.g., see the tropical Grassmanian in Example in Sect. 3.5. A different use case for several media objects for the same model is displayed for the discrete catenoid and helicoid model in Example in Sect. 3.1. One media object shows a catenoid, whereas the other media object contains a dynamic rendering of the transformation from the catenoid to the helicoid.
The various file formats for one media object are meant to display one view of the model on several backends. For instance, the discrete catenoid media object comes with a PNG file to be displayed in a standard web browser and with an OBJ file which allows 3-dimensional interactive visualization with a suitable viewer software. The data files comprising the media objects are stored in the file system separately from the model database. The media objects of a model contain links to those data files, see Sect. 4.1.
In principle, we do not restrict the file formats for data files of any media objects. This makes the DGD Gallery very flexible, but this also creates potential trouble with file formats that are uncommon. We support the direct visualization of a few well chosen standard file formats. So far these include the following: PNG and JPG (for raster image data), SVG and PDF (for vector graphics), OBJ (for 3-dimensional geometric data), MOV, MP4, and OGV (for video content), POLY (for polymake data), and others. Interactive content is not excluded, see Sect. 5.3, but the danger of a particularly low stability over time should be well considered. We rely on the review process for a sound selection.
4.3 Versioning
The DGD Gallery tracks the history of each model via the version attribute, see Fig. 6. Editing a model amounts to adding a new version with modified content. If a model is deleted, all versions of the model and the data files linked are deleted from the database. A data file is kept in the file system as long as there exists a link to it from some version of a model.
The version system is particularly useful for models with several authors who can collaborate through our front end.
It is worth noting that we also allow published models to be edited further and resubmitted. Upon acceptance this new version will appear as the current version of the model on the web page. The previously published versions remain visible and can be compared. This way authors can keep their models up to date; see also Sect. 5.2 below which describes our migration process.
4.4 Users
The users of the DGD Gallery are represented by their usernames, i.e., their login names on the web-site. The access is password restricted, see also Sect. 5.1. In addition to the username and password we store the name and email address of the person that is associated with the user.
A user has a global user-role that can take the values admin, reviewer, or author. In addition to the global user-role we store model-roles for each model associated with a user. A user can be the owner or an editor of a model. The read and write access to models is restricted such that it is based on a combination of the global user-role, the model-role and the state of the model, Fig. 7. This implementation allows reviewers to act as model authors but prevents them from approving their own models.
A notable design decision is that a reviewer can modify a submitted model to correct obvious typos and other minor changes before approval. Each owner of a model can invite other users to become either owners or editors of that model.
4.5 Submission Process
The DGD Gallery uses a submission system to publish models on the web-site. The idea is that a board of reviewers approves, sends back for revision, or rejects a submitted model. The review process should concern the quality of the content and address technical issues with the digital data. The review board has to work out and agree on some quality criteria for a model.
During its life-cycle a model has assigned a status value. A newly created model starts its life in edit state. It can be previewed and edited by the owners of the model, typically the creator of the model, and any additional user with the editor model-role, see Sect. 4.4.
A model can be submitted by a user with the owner model-role. The status of the model changes to pending. A model with pending status is read-only for the owner and all editors.
Reviewers can preview and edit pending models. A reviewer edits a model to resolve small issues such as typos. If the quality of a model is sufficiently high then a reviewer can accept a model. The status of the model is changed to approved. If the content has flaws or technical issues that can be resolved by the creator of the model, the reviewer sends the model back to edit state. Any action by a reviewer is accompanied by a review text, which is presented to the authors of the model.
If a model is sent back for revision, the authors can edit the model according to the review text and resubmit. If the model is rejected it can neither be edited nor resubmitted. A model will be rejected if it contains major flaws or its content is not appropriate for publication in the DGD Gallery.
Approved models become publicly available on the DGD Gallery web-site (see Sect. 4.6). To further improve public models, e.g. by correcting errors or replacing outdated file formats, a new version of an approved model can be created, which is back in edit state. To publish the new version it has to be submitted und undergo the revision process again.
The model submission system dispatches messages to the users of the DGD Gallery on every model status change. Reviewers are notified about submitted models. Model owners/editors are notified upon acceptance, rejection, or call for revision.
In principle any reviewer can accept, send back, or reject a model. We rely on a reasonable communication between the reviewers to organize the review process. Accepting a model is based on formal correctness, technical soundness, mathematical content and visualization quality.
4.6 Publication and Licensing
Content that has been approved by the board of reviewers is published on the DGD Gallery web page. The presentation of the content on this page is equivalent to the preview during edit state of the model. The key defines the permanent absolute URL of a model:
The content of the DGD Gallery is published under the Creative Commons Attribution-ShareAlike 4.0 International license, short CC BY-SA 4.0, see [28]. This means in particular that we allow for our data to be used commercially, enabling newspapers or commercial web blogs to include content from the gallery without further complications. Appropriate credit must be given if any content is reproduced or used, and this includes a link to the DGD Gallery.