Skip to content

Commit ad43e87

Browse files
formanforman
committed
Docs and deps update
1 parent a1c53f1 commit ad43e87

File tree

6 files changed

+575
-399
lines changed

6 files changed

+575
-399
lines changed

‎README.md‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -120,19 +120,19 @@ Install the S2GOS controller packages as described in
120120

121121
To run all checks, execute
122122

123-
```commandline
123+
```bash
124124
pixi run checks
125125
```
126126

127127
To run all tests, execute
128128

129-
```commandline
129+
```bash
130130
pixi run tests
131131
```
132132

133133
To generate a coverage report, execute
134134

135-
```commandline
135+
```bash
136136
pixi run coverage
137137
```
138138

@@ -153,7 +153,7 @@ would likely be best to implement the required changes in the respective
153153
Eozilla packages. For this, check out the Eozilla sources directly next
154154
to this project's sources to achieve this folder structure:
155155

156-
```commandline
156+
```
157157
<projects>/
158158
├── s2gos-controller/
159159
│ ├── s2gos-client/
@@ -168,17 +168,24 @@ to this project's sources to achieve this folder structure:
168168
└── ...
169169
```
170170

171-
Then, during development, change `sen4cap-controller/pyproject.toml`
172-
as follows
171+
For development, change the root `pyproject.toml` file as follows
173172

174-
1. Comment out the dependencies `cuiman`, `gavicore`, and `wraptile` in the
175-
`[project.dependencies]` table.
173+
1. Comment out the dependencies `cuiman`, `gavicore`, etc. in the
174+
`[tool.pixi.dependencies]` table.
176175

177-
2. Uncomment the editable PyPI dependencies for `cuiman`, `gavicore`,
178-
and `wraptile` in the `[tool.pixi.pypi-dependencies]` table.
176+
2. Uncomment the editable PyPI dependencies for `cuiman`, `gavicore`, etc. in
177+
the `[tool.pixi.pypi-dependencies]` table.
179178

180-
Then run once more
179+
The run
181180

182-
```commandline
183-
pixi install
181+
```bash
182+
pixi i
184183
```
184+
185+
to make the changes effective. Check with
186+
187+
```bash
188+
pixi ls
189+
```
190+
191+
which should now list the Eozilla packages as editable.

‎docs/index.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
11
# DTE-S2GOS Controller
22

3+
The Python control layer for the ESA DTE-S2GOS synthetic scene generator service
4+
35
![logo.svg](assets/logo.svg){ .centered-logo width="300"}
46

5-
<br>
6-
<br>
7-
The Python control layer for the ESA DTE-S2GOS synthetic scene generator service.
7+
The _Digital Twin Earth Synthetic Scene Generator and Observation Simulator_
8+
(DTE-S2GOS) project consists in the development of a new component of the
9+
[ESA Destination Earth Initiative](https://destination-earth.eu/)
10+
to be implemented in the [ESA DestinE Platform](https://platform.destine.eu/)
11+
as a pre-operational service. The primary objective of DTE-S2GOS is to develop a
12+
comprehensive and accurate simulation framework that can generate physically
13+
realistic synthetic 3D scenes of the Earth and simulate ground-based or spaceborne
14+
remote sensing observations, among other with the
15+
[Eradiate Radiative Transfer Model](https://github.com/eradiate/eradiate).
16+
817
**Note, this project and its documentation is still in an early development stage.**
9-
<br>
10-
<br>
1118

1219
[The Project](https://dte-s2gos.rayference.eu/about/){ .md-button .md-button--primary }
13-
[Get Started](client-cli){ .md-button .md-button--primary }
20+
[Get Started](installation){ .md-button .md-button--primary }

‎docs/installation.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Installation
2+
3+
## Using pip
4+
5+
The S2GOS controller packages are not yet deployed on PyPI, therefore
6+
installing it as a package using `pip` is not yet available.
7+
8+
## Using conda/mamba
9+
10+
The S2GOS controller packages are not yet deployed on conda-forge, therefore
11+
installing it using as a conda package using `conda` or `mamba` is not yet available.
12+
13+
## Using pixi
14+
15+
The S2GOS controller packages are not yet deployed on conda-forge, therefore
16+
installing it as a conda package using `pixi` is not yet available.
17+
18+
## Using GitHub
19+
20+
To install the S2GOS controller packages from their sources on GitHub you'll
21+
need to install both [git](https://git-scm.com/install/) and
22+
[pixi](https://pixi.sh/latest/installation/) first. Then:
23+
24+
```bash
25+
git clone https://github.com/eo-tools/sen4cap-client.git
26+
cd s2gos-controller
27+
pixi install
28+
pixi shell
29+
```
30+
31+
The installed development environment includes also JupyterLab so the recommended
32+
way to get started is to take a look at the notebooks in the `notebooks` folder.
33+
34+
```bash
35+
cd notebooks
36+
jupyter-lab
37+
```
38+
39+
## Getting started
40+
41+
After installing the S2GOS controller packages in your Python environment
42+
and activating it (conda/mamba: `conda activate <your-env>`, pixi: `pixi shell`)
43+
make sure the respective command-line tools are accessible: Type
44+
45+
```bash
46+
s2gos-server --help
47+
```
48+
49+
and
50+
51+
```bash
52+
s2gos-client --help
53+
```
54+
55+
to get an overview of the available commands and options.
56+
57+
You can then run the S2GOS server with one of the development services
58+
or use the deployed server. To run the development service with a local
59+
process executor run
60+
61+
```bash
62+
s2gos-server dev -- wraptile.services.local:service
63+
```
64+
65+
To run the S2GOS gateway server with a local Airflow instance (assuming
66+
the local Airflow webserver runs on http://localhost:8080):
67+
68+
```bash
69+
s2gos-server dev -- wraptile.services.airflow:service --airflow-password=abcd1234
70+
```
71+
72+
The next step is configure the client, which will also serve as default configuration
73+
for the client's Python API and its GUI:
74+
75+
```bash
76+
s2gos-client configure
77+
```
78+
79+
Test:
80+
81+
```bash
82+
s2gos-client list-processes
83+
```
84+
85+
## Development
86+
87+
Install the S2GOS controller packages as described in
88+
[Installation / Using GitHub](#using-github) above.
89+
90+
## Linting and Testing
91+
92+
To run all checks, execute
93+
94+
```bash
95+
pixi run checks
96+
```
97+
98+
To run all tests, execute
99+
100+
```bash
101+
pixi run tests
102+
```
103+
104+
To generate a coverage report, execute
105+
106+
```bash
107+
pixi run coverage
108+
```
109+
110+
## Implementing Enhancements
111+
112+
The S2GOS controller code relies heavily on the
113+
[Eozilla](https://eo-tools.github.io/eozilla/) packages
114+
115+
* [wraptile](https://github.com/eo-tools/eozilla/tree/main/wraptile),
116+
which provides the gateway server implementation,
117+
* [cuiman](https://github.com/eo-tools/eozilla/tree/main/cuiman),
118+
which provides the client CLI, GUI, and API implementations, and
119+
* [gavicore](https://github.com/eo-tools/eozilla/tree/main/gavicore)
120+
which provides common OGC model classes and basic utilities.
121+
122+
Should S2GOS controller require non-S2GOS-specific enhancements it
123+
would likely be best to implement the required changes in the respective
124+
Eozilla packages. For this, check out the Eozilla sources directly next
125+
to this project's sources to achieve this folder structure:
126+
127+
```
128+
<projects>/
129+
├── s2gos-controller/
130+
│ ├── s2gos-client/
131+
│ ├── s2gos-server/
132+
│ └── ...
133+
└── eozilla/
134+
├── appligator/
135+
├── cuiman/
136+
├── gavicore/
137+
├── procodile/
138+
├── wraptile/
139+
└── ...
140+
```
141+
142+
For development, change the root `pyproject.toml` file as follows
143+
144+
1. Comment out the dependencies `cuiman`, `gavicore`, etc. in the
145+
`[tool.pixi.dependencies]` table.
146+
147+
2. Uncomment the editable PyPI dependencies for `cuiman`, `gavicore`, etc. in
148+
the `[tool.pixi.pypi-dependencies]` table.
149+
150+
The run
151+
152+
```bash
153+
pixi i
154+
```
155+
156+
to make the changes effective. Check with
157+
158+
```bash
159+
pixi ls
160+
```
161+
162+
which should now list the Eozilla packages as editable.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ copyright: Copyright &copy; 2025 ESA DTE-S2GOS Team
1010

1111
nav:
1212
- Overview: index.md
13+
- Installation: installation.md
1314
- Architecture: architecture.md
1415
- Client CLI: client-cli.md
1516
- Client API: client-api.md

0 commit comments

Comments
 (0)