====== 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 [[groimp-platform:workbench|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 [[:user-guide:additional_interfaces|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 [[https://javadoc.grogra.de/projectmanager/de/grogra/projectmanager/ProjectImpl.html|project]].

===== Project design and main files =====

A project requires three files to be openable in GroIMP:
  - 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.
  - 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.
  - 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: 
  - the **project registry** and the **graph** can be renamed as long as their references are also renamed.
  - 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.
==== Project registry (GS) ====

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: 

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

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:

<code xml>
<?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
</code>

==== Project graph ====

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:
  - The **main graph**: it is the graph build by the queries, rules, and objects insertions. This is the graph manipulated by the user. 
  - 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:

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

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:

<code xml>
<?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>
</code>

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.


==== Java resources file ====

The third required file to open a project. It follow the same definition as the java [[https://docs.oracle.com/javase/tutorial/deployment/jar/manifestindex.html|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:
<code>
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
</code>

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).



==== Compressed project (GSZ) ====

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/ *''