Differences

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

--- 01_user_documentation:groimp-platform:gs-project [2025/01/24 11:59] – ↷ Links adapted because of a move operation gaetan
+++ 01_user_documentation:groimp-platform:gs-project [2025/01/24 17:04] (current) – removed gaetan
@@ Line 1: / Line 1: @@
-====== 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 [[01_user_documentation: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 [[01_user_documentation: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/ *''