GroIMP Project

The main entity you work on in GroIMP is the project. A project may consist of various parts, e.g., files, source code, a scene (2D, 3D, or other), resource objects like data sets, 3D materials or the like. Several projects can be open at the same time, each in its own main window.

The Project object is closely related to the Workbench object.

To simplify:

• a Project is the set of resources that enables to open an entity that can be processed by GroIMP.
• a Workbench is the set of windows that enables the user to interact with the project. A workbench is created around a project. Even in interfaces that do not create a GUI (headless for instance), a workbench is created and used to process the project.

Note for developers, a GroIMP project is slightly different from the code implementation of a project.

A project requires three files to be openable in GroIMP:

1. The project registry: Named project.gs by default. It is an XML file that includes all the registry content of the project. I.e. the list of all resources to load in the project, as well as “how” to load them.
2. The Graph: Named graph.xml by default. It is an XML file that describe the graph state of the project graph in the project. It store the current state of the graph, which enables to save and reload a project after running it.
3. The Java resources file: Named MANIFEST.MF in the repository META-INF. This is a text file that list all files of the project and their types.

Note that:

1. the project registry and the graph can be renamed as long as their references are also renamed.
2. The project can be compressed into a .gsz file. In that case, the three files (and all other resources) are contained in the .gsz file.

The project registry is a XML file. It hold the mapping between the project resources and the GroIMP way to load them (Which java classes, which parameters, …).

It's minimal content is:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://grogra.de/registry" graph="graph.xml"/>

The first line describe the xml format. Then the second line is the main tag of the file: <project/>. All the content of the project registry have to be inserted under this tag. The tag also define the name of the graph file it describes.

An actual registry project look like:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://grogra.de/registry" graph="graph.xml">
<!-- The list of required groimp plugin for running the project -->
 <import plugin="de.grogra.imp" version="2.1.5"/>
 <import plugin="de.grogra.pf" version="2.1.5"/>
 
<!-- All the registry items required to be loaded --> 
<registry>
<!-- List of the projects objects (Here we only have one file, but shaders, images, ... would be listed here as well) -->
 <ref name="project">
   <ref name="objects">
    <ref name="files">
     <de.grogra.pf.ui.registry.SourceFile mimeType="text/x-grogra-rgg" name="Model.rgg" systemId="pfs:Model.rgg"/>
     </ref>
    </ref>
   </ref>
 
   <!-- A list of the layout used to reload the project in the same workbench layout --> 
   <ref name="workbench">
   <ref name="state">
    <de.grogra.pf.ui.registry.Layout name="layout">
    ...
    </de.grogra.pf.ui.registry.Layout>
   </ref>
  </ref>
 
</registry>
 
</project

The current state of the project graph. It is a XML file as well. It is a slightly more complete version of the graph you can see in the 2d graph panel (panels>2d>graph). It contains all roots of the project. Usually, there are only two:

1. The main graph: it is the graph build by the queries, rules, and objects insertions. This is the graph manipulated by the user.
2. The meta graph: A graph containing additional meta information. For instance it includes the resources nodes (e.g. shaders).

Note that despite being called both graph, they are more sub-graph of the project graph.

The minimal content of the graph is:

<?xml version="1.0" encoding="UTF-8"?>
<graph xmlns="http://grogra.de/xmlpersistence" xmlns:gx="http://grogra.de/xmlpersistence"/>

The first line is the required xml description. The second contains the main tag of the file: <graph/>. It also needs to define the xmlns attributes used by GroIMP to load the content described in the file.

An actual graph (with only the rggroot) can look like:

<?xml version="1.0" encoding="UTF-8"?><graph xmlns="http://grogra.de/xmlpersistence" xmlns:gx="http://grogra.de/xmlpersistence">
 
<!-- The first root: the meta graph -->
 <node root="MetaGraph" id="1" type="de.grogra.graph.impl.Node">
  <data gx:name="extentIndex" gx:value="7"/>
  <node id="29" type="Model" edges="+">
   <data gx:name="extentIndex" gx:value="7"/>
   <object gx:name="initialTurtleState" color="14" length="100.0" diameter="0.1" tropism="0.0" parameter="0.0" carbon="0.0" heartwood="0.0" internodeCount="0"/>
  </node>
 </node>
 
<!-- The second root -->
 <node root="MainGraph" id="0" type="de.grogra.graph.impl.Node">
  <data gx:name="extentIndex" gx:value="7"/>
  <node id="21" type="de.grogra.rgg.RGGRoot" edges="+"/>
 </node>
</graph>

Notice that, with this representation, successor edges are implicitly described. The first node under another <node/> tag is seen as the successor. Additional edges would be added as <edge/> tags.

The third required file to open a project. It follow the same definition as the java manifest file.

It cannot be renamed or moved. It needs to be META-INF/MANIFEST.MF.

This is a simple text file that list the files used in the project including the project registry and graph file.

A simple example of its content is:

Name: project.gs
Content-Type: application/x-grogra-registry+xml

Name: Model.rgg
Content-Type: text/x-grogra-rgg; charset=UTF-8

Name: graph.xml
Content-Type: application/x-grogra-graph+xml

Each file is mapped with its name and a MimeType (i.e. the explicit type of the file. Several files could have the same extension but be processed differently).

A project can be compressed into an archive. The standard GroIMP extension is .gsz, but is is a simple archive. Any .zip, 7z, or other archive format would work (as long as you rename the extension .gsz).

The archive contains all the content of the project. It can be viewed, modified, or extracted with any archive tools on you computer.

Note that:

• GroIMP requires the archive extension to be .gsz.
• The archive need to follow the same compression order as a java package. Thus, if you want to compress the project manually you need to include first the META-INF directory.

For instance to compress a project in the current folder you can use the command:

zip -r myProject.gsz META-INF/ *