Differences

This shows you the differences between two versions of the page.

--- groimp-platform:gs-project [2024/12/16 13:11] – created gaetan
+++ groimp-platform:gs-project [2025/01/22 15:54] (current) – Tim
@@ Line 3: / Line 3: @@
 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,
+The Project object is closely related to the [[groimp-platform:workbench|Workbench]] object.
-  * a Project is the set of resources that enables to open the working entity that can be processed by GroIMP.
-  * a Workbench is the set of windows that enables the user to use 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.
+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]].
@@ Line 11: / Line 13: @@
 ===== 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 ====
-==== Compressed project (GSZ) ====
+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:
-===== Create a project =====
+''zip -r myProject.gsz META-INF/ *''