Differences

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

--- user-manual:ch01 [2024/04/29 15:22] – [GroIMP Interfaces] gaetan
+++ user-manual:ch01 [2025/06/17 19:27] (current) – barley1965
@@ Line 1: / Line 1: @@
-====== Table of Contents ======
+====== Installation ======
-    * [[:User-Manual:ch01#system_requirements|System Requirements]]
-    * [[:User-Manual:ch01#download|Download]]
-    * [[:User-Manual:ch01#install_from_binaries|Installation from binaries]]
-    * [[:User-Manual:ch01#running_groimp|Running GroIMP]]
-      * [[:User-Manual:ch01#running_groimp|From a Shortcut]]
-      * [[:User-Manual:ch01#running_groimp|From the Command Line]]
-      * [[:User-Manual:ch01#running_groimp|Additional Options]]
-      * [[:User-Manual:ch01#running_groimp|GroIMP Interfaces]]
-    * [[:User-Manual:ch01#plugin_architecture|Plugin Architecture]]
-====== Requirements ======
+===== Requirements =====
-GroIMP is
+GroIMP is written in Java, which means it should follow Java's WORA-principle (Write Once, Run
-written in Java. Thus,  it should follow Java's WORA-principle (Write Once, Run
 Anywhere) and should run on every Java-capable platform. GroIMP has been tested
-successfully on Unix and  Windows platforms.
+successfully on Mac, Linux and  Windows platforms.
-GroIMP 2.1.3 requires
+GroIMP 2.2 requires the installation of a **Java runtime environment of version 21**. This
-the installation of a  Java runtime environment of version 17. Which
+can be obtained from Oracle at [[https://www.oracle.com/de/java/technologies/downloads/#java21]].
-can be obtained from Oracle at [[https://www.oracle.com/|www.oracle.com]].
-For a reasonably
+For a reasonably performant runtime behaviour, at least 256 MB RAM and a 1 GHz processor are
-performant runtime behaviour, at least 256 MB RAM and a 1 GHz processor are
 recommended.
-====== Download ======
+===== Download =====
-The binary distribution of GroIMP is available on the [[https://gitlab.com/grogra/groimp/-/releases|gitlab release section]] as a zip-file, windows exe, or debian release.
+The binary distribution of GroIMP  is available on our website [[https://download.grogra.de/|download.grogra.de]] as a zip-file, windows exe, or Debian/Ubuntu release.
-====== Installation Installation from binaries ======
-The windows exe and debian release are executable files that will extract and install GroIMP on your computer. It will also provide you to create a menu entry and a shortcut.
-Mac users need to download the zip-file, extract it and run GroIMP from command line.
+===== Installation from binaries =====
+ It will also provide you with the possibility to create a menu entry and a shortcut.
+==== Windows ====
+The windows exe is an executable file that will extract and install GroIMP on your computer.
+While you are downloading the file you might get some warning from your web browser that the software is not certified by Microsoft. Please ignore this warning, as we neither had the funding nor the time to go through the certification process.
+Please double click on the downloaded file (make sure you have administrator rights on your machine for installation), and follow the instructions one by one:
+{{:tutorials:beginnerstut_image4.png?293x204}} {{:tutorials:beginnerstut_image5.png?295x202}}
+Normally, click on ‘I Agree’, then on ‘Next’. Choose the destination folder, then the maximum heap size for Java. This allocates a certain amount of RAM (random access memory) to the Java Virtual Machine on which GroIMP is running. By default, 1500 MB are allocated, but you can allocate up to 50 per cent of the RAM available on your machine to Java, without any problem (so on a machine with 10 GB RAM you can enter 5000):\\
+{{:tutorials:beginnerstut_image6.png?284x193}} {{:tutorials:beginnerstut_image7.png?282x192}}
+After this you click on ‘Install’ and wait for the installation to finish (this can take more than ten minutes).
+After the installation, a folder “GroIMP-2.2” should be available under something like this address: “C:\Program Files\”.
+GroIMP will now be available either on your desktop or in the list of programmes:
+{{:tutorials:beginnerstut_image8.png?82x73}}
+==== Mac OS ====
+Mac users need to download the zip-file, extract it and run GroIMP from the command line.
 The directory structure of the zip-file has to be preserved, check
@@ Line 38: / Line 54: @@
 into one  and the same directory).
-After extraction of the zip-file, the following files, among others, are present in the installation
+After extraction of the zip-file, the following files, amongst others, are present in the installation
 directory:
 `README`
-This plain text file contains additional information about the GroIMP distribution. Read it
+This plain text file contains additional information about the GroIMP distribution. Please read it
 carefully.
@@ Line 49: / Line 65: @@
 This plain text file contains  instructions for the installation of the GroIMP
-distribution, legal notices and other information. Read it carefully. If you
+distribution, legal notices and other information. Please read it carefully. If you
-have troubles with the installation procedure described in this manual, consult
+have trouble with the installation procedure described in this manual, please consult
-the file `INSTALL` a solution.
+the file `INSTALL` for a solution.
 `plugins`
@@ Line 63: / Line 79: @@
 environment to start the GroIMP application.
-====== Running GroIMP ======
-Because `core.jar` is an executable java archive, it is possible to start GroIMP just by (double-)clicking on the file in your system's file browser as you would do it with a usual executable file. This requires a suitable setup of your file browser, see the documentation of the browser and your Java installation if it does not already work.
+==== Ubuntu & Debian ====
-==== From a Shortcut ====
-You can set up your desktop to show a menu entry for GroIMP. How this is done depends on your system. Usually your system provides a menu editor where you can create a new menu entry and specifiy the command to be executed when the entry is activated. Choose the command as you would do on command line.
+The .deb file is an executable file that will extract and install GroIMP on your computer.
-==== From the Command Line ====
+In most modern Ubuntu systems you can just click on the downloaded deb file and it will open the package manager which allows you to install the software.
+If this is not possible you can use ''sudo dpkg -i /path/to/groimp.deb'' in a command line.
+=== Increasing heap space on Linux ===
+If you want to start GroIMP with additional heap space you can do so from the command line:
+<code>
+groimp -Xmx Xmx5G
+</code>
+==== Others ====
+As a java software it is possible to execute GroIMP on any system that can run a java virtual machine of version 21. This includes almost any version of Linux as well as some other systems.
+For this case we provide an archive with the compiled jar on the Gitlab release page.
+This can then be executed with java -jar core.jar
+===== Running GroIMP =====
+Because `core.jar` is an executable java archive, it is possible to start GroIMP just by (double-)clicking on the file in your system's file browser as you would do with a usual executable file. This requires a suitable setup of your file browser, see the documentation of the browser and your Java installation if it does not already work.
+=== From a Shortcut ===
+You can set up your desktop to show a menu entry for GroIMP. How this is done depends on your system. Usually your system provides a menu editor where you can create a new menu entry and specifiy the command to be executed when the entry is activated. Choose the command as you would do on the command line.
+=== From the Command Line ===
 The file `core.jar` in your installation directory of GroIMP's binary distribution is the entry-point for starting GroIMP. Running GroIMP from the command line is easy:
@@ Line 85: / Line 125: @@
 > **java -Xverify:none -jar "C:\\Program Files\\GroIMP\\core.jar"**
-==== Additional Options ====
+Alternatively, if you wish to start GroIMP from a batch file from your cmd console in Windows, you could write a file called groimp.bat (which you would place in your home directory, C:\\Users\\myself\\, where 'myself' is your user directory) with the following content:
+> **cd "C:\Program Files\GroIMP 2.2"**
+> **"C:\Program Files\Java\jdk-22\bin\javaw.exe" -Xmx3000m -Xss20M -noverify -jar core.jar**
-=== Java Parameters ===
+where "C:\Program Files\Java\jdk-22\bin\javaw.exe" is an example of the placement of your javaw version, assuming we use jdk22.
-The **java** command has several options which influence the runtime behaviour, see the documentation of your Java installation. These options have to be specified before the `-jar` option. E.g., for the Java runtime environment of Sun, the option `-Xmx` specifies the maximum amount of heap memory size that should be allocated. The default value of this option may be much smaller than your installed main memory size. In this case GroIMP cannot benefit from your memory until you specify the `-Xmx` option as in
+===== Testing GroIMP for the first time =====
+After you followed the installation instruction and started the software, you should be able to proceed the steps shown in the animation below:
+{{ :user-manual:test_groimp.gif |}}
+In the editor "GREEN" is replaced by "BLUE" (not easy to see)
+===== Trouble shoot =====
+==== Windows: GroIMP doesn't start ====
+Even if you have installed the right version of java it can happen that the GroIMP installer is picking a wrong version of Java from your system. {{ :tutorials:copy.png?100|}}
+In this case you have to edit the shortcut to enter the right path:
+. Find java 21 on your computer (most likely somewhere in "C:\Program Files"
+. Right click on the the GroIMP desktop shortcut and select Properties (see image on the right)
+. In the Properties find the filled target (see image below)
+. Change the first path to the javaw.exe of java 21.
+{{ :tutorials:prefrences.png?200 |}}
+==== GroIMP is too small / too large ====
+On modern screens Java swing applications sometimes struggle with the scaling making the font and the buttons way too small. To fix this you can just manually scale it with the following [[#java_parameters | java parameter]]:
+<code>
+-Dsun.java2d.uiScale=2.5
+</code>
+Instead of 2.5 you can use whatever scale fits for your screen, you might have to try this out a few times.
+To apply this on Windows please refer to ([[#windowsgroimp_doesn_t_start | Windows: GroIMP doesn't start ]] and to apply this on Debian/Ubuntu to [[#increasing_heap_space_on_Linux | Increasing heap space on Linux]].
+===== Additional Options =====
+==== Java Parameters ====
+The **java** command has several options that influence the runtime behaviour, see the documentation of your Java installation. These options have to be specified before the `-jar` option. E.g., for the Java runtime environment of Sun, the option `-Xmx` specifies the maximum amount of heap memory that should be allocated. The default value of this option may be much smaller than your installed main memory size. In this case GroIMP cannot benefit from your memory until you specify the `-Xmx` option as in
 > **java -Xmx400m -jar path/to/core.jar**
-which allows a maximum heap memory allocation of 400 MB. If you encounter `OutOfMemoryError`s when running GroIMP, you have to specify this option with a larger value.
+which allows a maximum heap memory allocation of 400 MB. If you encounter `OutOfMemoryError`s when running GroIMP, you have to specify this option with a larger value. Note that the opposite may happen, i.e. a too generous memory allocation might prevent GroIMP from starting at all. In that case you have to lower the allocated memory again until it works.
-=== GroIMP Parameters ===
+==== GroIMP Parameters ====
-The command line also enables to provides parameters to GroIMP. These parameters need to be passed AFTER the //core.jar// file. E.g.
+The command line also enables to send parameters to GroIMP. These parameters need to be passed AFTER the //core.jar// file. E.g.
 > **java -jar core.jar --project-tree**
@@ Line 103: / Line 184: @@
 The complete list of GroIMP parameters can be found [[:user-guide:advanced-groimp-arguments|here]].
-==== GroIMP Interfaces ====
+===== GroIMP Interfaces =====
+See [[:user-guide:additional_interfaces|GroIMP interfaces]] for more details and tutorials.
 GroIMP can be run from different interfaces. By default, GroIMP use the "imp" interface which is its Graphical User Interface (GUI).
@@ Line 109: / Line 192: @@
 GroIMP can also be started //headless//, from //CLI//, or //API//.
-To define which interface is used, when starting GroIMP you need to pass the parameter //-a//. E.g.
+To define which interface is used when starting GroIMP you need to pass the parameter //-a//. E.g.
  > **java -jar core.jar -a api**
-More information can be found for using GroIMP [[:groimp-platform:interfaces:headless|headless]], [[:groimp-platform:interfaces:cli|CLI]], and [[:groimp-platform:interfaces:api|API]].
+More information can be found for using GroIMP [[:user-guide:additional_interfaces:headless|headless]], [[:user-guide:additional_interfaces::cli|CLI]], and [[:user-guide:additional_interfaces:api|API]].
 ===== Plugin Architecture =====
@@ Line 121: / Line 204: @@
 Installation of Plugins for the Java Image I/O Framework.
-GroIMP requires only a Java runtime environment in order to run. However, the capabilities of some parts of the Java runtime environment can be extended by the installation of additional plugins. GroIMP makes use of the Java Image I/O Framework which provides such a pluggable architecture: The user may install plugins which add support for an image file format to the Java Image I/O Framework. If the standard installation of the Java runtime environment does not support an image file format you need, please consult the [[http://java.sun.com/j2se/1.4.2/docs/guide/imageio/index.html|Java Image I/O pages]] for a suitable plugin.
+GroIMP requires only a Java runtime environment in order to run. However, the capabilities of some parts of the Java runtime environment can be extended by the installation of additional plugins. GroIMP makes use of the Java Image I/O Framework which provides features such as a pluggable architecture: The user may install plugins which add support for an image file format to the Java Image I/O Framework. If the standard installation of the Java runtime environment does not support an image file format you need, please consult the [[http://java.sun.com/j2se/1.4.2/docs/guide/imageio/index.html|Java Image I/O pages]] for a suitable plugin.
 ==== GroIMP Plugins ====
-GroIMP is developed around a plugin architecture. New plugin can easily be added to your GroIMP installation by simply adding them to the loading directory of GroIMP.
+GroIMP is developed around a plugin architecture. New plugins can easily be added to your GroIMP installation by simply adding them to the loading directory of GroIMP.
-On startup GroIMP load all plugins under it's installed path/plugins, as well as plugins in the //user plugin path//. The //user plugin path// can be modified in the GroIMP options, and is by default at ~/.grogra.de-platform/plugins/.
+On startup GroIMP loads all plugins under its installed path/plugins, as well as plugins in the //user plugin path//. The //user plugin path// can be modified in the GroIMP options, and is by default at ~/.grogra.de-platform/plugins/.
 GroIMP plugins can be installed/ removed/ modified from within GroIMP with the [[:User-Guide:pluginmanager| Plugin Manager]].
-A complete list of available plugin can be found at [[https://grogra.gitlab.io/groimp-utils/plugin_web_explorer/]]
+A complete list of available plugins can be found at [[https://grogra.gitlab.io/groimp-utils/plugin_web_explorer/]]