feat: #11 major review of CLI usage (#19)

.github/workflows/tests.yml

@@ -1,36 +1,63 @@
-# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
-
-name: Node.js CI
+name: Poto-Siril
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
-
     strategy:
       matrix:
         node-version: [18.x, 20.x, 22.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+      - run: npm install
+      - run: npm run check-types
 
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "npm"
+      - run: npm install
+      - run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "npm"
+      - run: npm install
+      - run: npm run test -- --coverage
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  test-cli:
+    runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-    - run: npm install
-    - run: npm run lint
-    - run: npm run check-types
-    - run: npm run test -- --coverage
-    - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v5
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "npm"
+      - run: npm install
+      - run: npm run test-cli

.vscode/launch.json

@@ -1,24 +1,22 @@
 {
-  "version": "0.2.0",
+  "version": "0.4.0",
   "configurations": [
     {
-      "name": "dispatch-dump",
+      "name": "dev-prepare-dataset1",
       "type": "node",
       "request": "launch",
       "runtimeExecutable": "node",
       "runtimeArgs": ["--nolazy", "-r", "ts-node/register/transpile-only"],
-
       "args": [
         "src/poto-siril.ts",
-        "dispatch",
-        "-p",
-        "src/tests/data/project1",
-        "-a",
-        "src/tests/data/asiair-dump1",
-        "-b",
-        "src/tests/data/bank",
+        "prepare",
+        "-i",
+        "tmp/asiair-dump",
+        "-i",
+        "tmp/bank",
+        "tmp/project"
       ],
-
+      "preLaunchTask": "npm: dev-prepare-ds1",
       "cwd": "${workspaceRoot}",
       "internalConsoleOptions": "openOnSessionStart",
       "skipFiles": ["<node_internals>/**", "node_modules/**"]

README.md

@@ -1,35 +1,48 @@
 # ![logo](./img/poto-siril_logo.png)
 
-Automatization around Siril (<https://siril.org/>) and ASIAIR for deep sky astrophotography.
+Automatization around Siril (<https://siril.org/>) for deep sky astrophotography.
 
 [![codecov](https://codecov.io/gh/TomyCesaille/poto-siril/graph/badge.svg?token=RCF9ZV8JZ9)](https://codecov.io/gh/TomyCesaille/poto-siril)
 
 ## What is it?
 
 **Poto-Siril is a CLI tool to automate the pre-processing of astrophotography images on top of Siril.**
 
-Poto-Siril's primary goal is to **overcome the repetitive and tedious** work when pre-processing multiple layers before compositing a (L)RGB image (e.g. narrowband filters with monochrome camera or color camera with dual-band filters). It works with images captured by a ZWO ASIAIR device out of the box or with any `fit` files that follows the same [naming convention and directory structure](#poto-siril-project-architecture).
+Poto-Siril aims to **overcome the repetitive and tedious** work when pre-processing multiple layers before compositing an (L)RGB image (e.g. narrowband filters with a monochrome camera or a color camera with dual-band filters).
+
+It works with images captured by a ZWO ASIAIR device out of the box or with any `fit` files that follow the same [file naming convention](#file-naming-convention) and [directory structure](#asiair-directory-structure-for-reference) (more support to come, help is welcomed 👋).
 
 ### Workflow 🚀
 
+The essence of Poto-Siril is about:
+
+- Organizing the raw data by grouping the multiple light sequences together in small groups (of the same filter, bulb, gain, etc...) tagged with the appropriate flats, darks, and biases.
+- Running Siril script(s) on each group of lights to retrieve the calibrated lights, following:
+
+```math
+Calibrated\_Light = \frac{Light\_Frame - Dark\_Frame}{Flat\_Frame}
+```
+
+- Stacking the calibrated lights to get a master light for each layer/filter.
+
 ![workflow](./img/poto-siril_workflow.png)
 
 ### In detail
 
-- **Easy import lights and flats from ASIAIR and search for associated darks and biases in bank folder**
-  Import one or several night sessions (lights and flats from `Autorun` or `Plan` mode with ASIAIR) and automatically pick the darks and bias from the bank folder (matching bulb, gain, binning, ...).
+- **Easy import of lights and flats from night session(s) and search for associated darks and biases in a bank folder**
+  Import one or several night sessions (e.g. lights and flats from `Autorun` or `Plan` mode with ASIAIR) and automatically pick the darks and biases from the bank folder (matching bulb, gain, binning, ...).
   A summary resumes the light sequence(s) and the calibration files associated.
-  ![dispatch](./img/poto-siril_dispatch.png)
+  ![dispatch](./img/poto-siril_prepare_summary.png)
 - **Complex Light - Flat matching**
-  The project consists of multiple night sessions where the flats changed over the time? e.g., a significant date gap between shooting sessions and the lights aren't coming with the same collimation and/or dust in the optical train.
-  Poto-Siril will auto-detect that and help you to associate the right flats to the right lights.
+  Poto-Siril helps to associate the right flats with the right lights when the project consists of multiple night sessions where the flats changed over time, e.g., a significant date gap between shooting sessions having a new  collimation tuning and/or new dust in the optical train.
+  ![flat_matching](./img/poto-siril_prepare_advanced-flats-matching.png)
 - **Multi-layers project structure**
-  The imported files ☝️ are organized by filters and light sets (bulb, gain & binning, if there's multiple combinations). Each light set will map to a light sequence in Siril that you preprocess separately.
-  👉 You can easily work on a LRGB or LRGBHaOIIISII project.
+  The imported files ☝️ are organized by filters and light sets (bulb, gain & binning, if there are multiple combinations). Each light set will map to a light sequence in Siril to be pre-processed separately.
+  👉 You can easily work on an LRGB or LRGBHaOIIISII project.
 - **Batch Siril script execution to pre-process the data**
-  Generates and run a Siril script (`.ssl` file) for each light set to preprocess the images based on a ssl file template that can be customized.
+  (Generates and) Runs a Siril script (`.ssl` file) to calibrate the lights for each light set, based on a customizable ssl file template.
 - **A/B testing** (PLANNED)
-  Run the (generated ☝️) Siril script with different parameters (e.g. rejection algo, sigma low/high thresholds) and compare the results.
+  Run the (generated ☝️) Siril script with different parameters (e.g. rejection algorithm, sigma low/high thresholds) and compare the results.
   Or run several different pre-processing scripts and compare the results.
 
 ### What it is not doing
@@ -47,6 +60,10 @@ npm i
 
 # For Unix based systems:
 chmod +x ./poto.sh
+
+# Test the CLI:
+./poto.sh -v
+# Should print `poto-siril 0.3.0`.
 ```
 
 Make sure to have `siril` registered in your PATH.
@@ -56,35 +73,59 @@ siril -v
 # Should print `siril 1.2.3`.
 ```
 
-### Poto-Siril project architecture
+### CLI commands
 
-The ASIAIR directory structure is as follows:
+```bash
+$POTO_PROJECT=jorislacance/deepsky/poto_2024_08_10_veil-nebula
+
+# Prepare a Poto project by importing imaging data session(s) and "static" calibration files (darks, biases).
+./poto.sh prepare \
+  # e.g. ASIAIR dump folder with Autorun directory filled with lights and corresponding flats.
+  -i jorislacance/deepsky/sessions/asiair_2024_08_10_veil-nebula \
+  # e.g. Bank folder where poto-siril will cherry-pick darks and biases as needed.
+  -i jorislacance/deepsky/_bank \
+  # 🎉 poto project directory destination.
+  $POTO_PROJECT
+
+# Batch pre-process all the lights, set by set (filter, bulb, gain, binning...) based on a Siril script template.
+export POTO_SCRIPT_TEMPLATE=src/process/mono_processing_process/1_preprocessing.ssf
+./poto.sh preprocess \
+  -t $POTO_SCRIPT_TEMPLATE \
+  $POTO_PROJECT
 
-```text
-# Root dump directory of an ASIAIR session
-├── Autorun
-│   ├── Light
-|   |   └── M42
-|   |       ├── Light_M42_10.0s_Bin1_S_gain360_20240320-203324_-10.0C_0001.fit
-│   |       ├── ...
-|   |       ├── Light_M42_10.0s_Bin1_S_gain100_20240321-223159_-10.0C_0001.fit
-|   |       └── ...
-│   └── Flat
-|       ├── Flat_1.0ms_Bin1_S_gain100_20240320-233122_-10.5C_0001.fit
-│       └── ...
-├── Plan
-│   # Same structure as Autorun.
-├── Live
-│   # Ignored in poto-siril
-├── Preview
-│   # Ignored in poto-siril
-├── Video
-│   # Ignored in poto-siril
-└── log
-    # Ignored in poto-siril
+# BONUS: Drop thumbnails and empty directories generated by ASIAIR.
+./poto.sh clear jorislacance/deepsky/sessions/asiair_2024_08_10_veil-nebula
 ```
 
-Poto project, once imported from the ASIAIR dump via the `dispatch` command, will be broke down into the following directory structure:
+### Pre-processing pipeline
+
+Usually, the pre-processing is a multi-step journey. The most usual case is to pre-process lights, eliminate bad ones in Siril directly, and go back to Poto-Siril to batch-run the stacking.
+
+You can chain multiple scripts to achieve the desired result.
+See [src/process/mono_processing_process/README.md](src/process/mono_processing_process/README.md) for a full example of a pre-processing pipeline.
+
+#### Create your own
+
+You can easily create your own by following the [mono_processing_process](src/process/mono_processing_process) example.
+
+Some remarks about **Poto-Siril script templates**:
+
+- `.ssf` extension like regular Siril scripts.
+- Poto-Siril dynamically overwrites the `{{poto-dir}}`, `{{lights}}`, `{{flats}}`, `{{darks}}`, `{{biases}}`, `{{process}}` & `{{masters}}` variables to the current light set to pre-process.
+
+### File naming convention
+
+Poto-Siril expects the files to follow the ASIAIR file naming convention `{Light|Flat|Dark|Bias}_{TARGET}_{EXPOSURE_TIME}{s|ms}_Bin{BINNING}_{FILTER}_gain{GAIN}_{DATE}-{TIME}_{TEMPERATURE}C_{SEQUENCE_NUMBER}.fit`.
+
+For example:
+
+- `Light_10.0s_Bin1_S_gain360_20240320-203324_-10.0C_0001.fit`
+- `Light_FOV_60.0s_Bin1_S_gain100_20240624-010840_-10.1C_0001.fit`
+- `Flat_1.0ms_Bin1_S_gain100_20240320-233122_-10.5C_0001.fit`
+- `Dark_300.0s_Bin1_S_gain100_20240320-233122_-10.5C_0001.fit`
+- `Bias_1.0ms_Bin1_S_gain100_20240320-233122_-10.5C_0001.fit`
+
+### Poto-Siril project architecture
 
 ```text
 # Poto project root directory
@@ -101,16 +142,16 @@ Poto project, once imported from the ASIAIR dump via the `dispatch` command, wil
 ├── H
 ├── O
 ├── ...
-└── any    👈 Biases & darks falls here. lights & flats too if no filter.
+└── any    👈 Biases & darks fall here. lights & flats too if no filter.
 ```
 
-> 💡 `S`, `H`, `O` are the filters names defined in ASIAIR (cf Filter Wheel settings).
+> 💡 `S`, `H`, `O` are the filter names defined in ASIAIR (cf Filter Wheel settings).
 
-### The bank folder
+### The bank folder (for reference)
 
-The bank folder is where you store your **darks** and **biases** files. The bank folder does not expect a specific structure as long as files are following the ASIAIR file naming convention.
+It's common to store the **darks** and **biases** in a 'bank folder' since they are quite static. Poto-siril doesn't expect any precise directory structure for a directory to act like a bank folder as long as the [file naming convention](#file-naming-convention) is respected.
 
-A good organization could be as follows:
+Example of structure:
 
 ```text
 # Bank directory
@@ -125,41 +166,32 @@ A good organization could be as follows:
 └── ...
 ```
 
-### CLI commands
-
-```bash
-# The location of your raw ASIAIR root folder (also named dump folder).
-export POTO_ASIAIR_DUMP=/Users/jorislacance/deepsky/dump_2024_08_10_veil-nebula
-
-# Drop thumbnails and empty directories from the ASIAIR dump folder.
-./poto.sh clean -a $POTO_ASIAIR_DUMP
-
-# Import lights to project, grouped per filter, and then light sets (bulb, gain & binning)
-# with the related calibration files (flats, darks and biases).
-export POTO_BANK=/Users/jorislacance/deepsky/_bank
-export POTO_PROJECT=/Users/jorislacance/deepsky/poto_2024_08_10_veil-nebula
-
-./poto.sh dispatch -a $POTO_ASIAIR_DUMP -b $POTO_BANK -p $POTO_PROJECT
-
-# Process each light set based on a Siril script template.
-export POTO_SCRIPT_TEMPLATE=src/process/mono_processing_process/1_preprocessing.ssf
+### ASIAIR directory structure (for reference)
 
-./poto.sh preprocess -p $POTO_PROJECT -s $POTO_SCRIPT_TEMPLATE
+```text
+# Root dump directory of an ASIAIR session
+├── Autorun
+│   ├── Light
+|   |   └── M42
+|   |       ├── Light_M42_10.0s_Bin1_S_gain360_20240320-203324_-10.0C_0001.fit
+│   |       ├── ...
+|   |       ├── Light_M42_10.0s_Bin1_S_gain100_20240321-223159_-10.0C_0001.fit
+|   |       └── ...
+│   └── Flat
+|       ├── Flat_1.0ms_Bin1_S_gain100_20240320-233122_-10.5C_0001.fit
+│       └── ...
+├── Plan
+│   # Same structure as Autorun.
+├── Live
+│   # Ignored in poto-siril
+├── Preview
+│   # Ignored in poto-siril
+├── Video
+│   # Ignored in poto-siril
+└── log
+    # Ignored in poto-siril
 ```
 
-### Full pre-processing
-
-See [src/process/mono_processing_process/README.md](src/process/mono_processing_process/README.md) for a full example of a pre-processing process.
-
-#### Create your own process
-
-You can easily create your own process by following the example of the [mono_processing_process](src/process/mono_processing_process) process.
-
-Some remarks about **Poto-Siril script templates**:
-
-- `.ssf` extension like regular Siril scripts.
-- Poto-Siril overwrite the `{{lights}}`, `{{flats}}`, `{{darks}}`, `{{biases}}`, `{{process}}`, `{{masters}}` variables to the current light set to pre-process.
-
 ## Development
 
 ```bash
@@ -175,12 +207,10 @@ npm run check-types
 # Generate dataset 1 for development
 npm run dev-spawn-ds1
 
-# Run the CLI dispatch-dump with the development dataset 1
-npm run dev-dispatch-ds1
+# Run the prepare command with the development dataset 1
+npm run dev-prepare-ds1
 ```
 
 ## Side Notes
 
-[Sirilic and Sirilot](https://siril.org/2018/11/sirilic-and-sirilot-two-very-useful-utilities-for-siril/) are two alternatives to automate Siril. This project is another take that emphasize lazyness of manipulating files in the file system, the love of Siril Scripting and A/B testing.
-
-"assembling the composition, making the pre-groups of lights with the right flats (days, filderss...)
+[Sirilic and Sirilot](https://siril.org/2018/11/sirilic-and-sirilot-two-very-useful-utilities-for-siril/) are two alternatives to automate Siril. This project is another take that emphasizes the laziness of manipulating files in the file system, the love of Siril Scripting, and A/B testing.

jest.config.ts

@@ -13,7 +13,7 @@ const jestConfig: JestConfigWithTsJest = {
   transformIgnorePatterns: [
     "/node_modules/(?!chalk|ansi-escapes)", // Ensure node_modules are transformed correctly
   ],
-  setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"], // Add custom matcher setup file
 };
 
 export default jestConfig;