starbash 0.1.8__py3-none-any.whl → 0.1.10__py3-none-any.whl

starbash/defaults/starbash.toml

@@ -3,6 +3,41 @@
 [repo]
 kind = "preferences"
 
+[aliases]
+# aliases can be used to map non standard (or non english) frame names to standard terms
+# This is also used to map filters based on common misspellings or variations.
+# We assume the first listed option in the list is the 'canonical' name used for printing etc...
+
+# frame types
+dark = ["dark", "darks"]
+flat = ["flat", "flats"]
+bias = ["bias", "biases"]
+light = ["light", "lights"]
+
+# file suffixes
+fits = ["fits", "fit"]
+
+# filter names
+SiiOiii = ["SiiOiii", "S2O3"]
+HaOiii = ["HaOiii", "HaO3"]
+
+None = ["None"]
+
+# Passes SII 672.4nm and H-Beta 486.1nm lines
+# Capturing of the two main emission wavebands in the deep red and blue at the same time
+#
+# The ALP-T dual band 3.5nm SII&Hb filter is a dual narrowband filter, which lets the deep
+# red Sulfur-II 672.4nm and the blue Hydrogen-Beta 486.1nm lines through and is primarily
+# engineered for color cameras to assist astrophotographers taking deep sky images with
+# superior SNR(Signal to Noise Ratio). With an FWHM halfbandwidth designed at 3.5nm and
+# achieving an optical density (OD) of 4.5 on unwanted wavelengths, it works strongly in
+# blocking light pollution, moonlight, and airglow, leding to enhanced contrast in nebulae
+# images by effectively passing the SII and H-beta emission lines signal only.
+#
+# http://www.antliafilter.com/pd.jsp?fromColId=2&id=160#_pp=2_671
+SiiHb = ["SiiHb", "S2Hb"]
+
+
 # FIXME, somewhere here list default patterns which can be used to identify NINA, ASIAIR, SEESTAR
 # raw repo layouts
 

starbash/main.py

@@ -6,7 +6,7 @@ import starbash.url as url
 import starbash
 
 from .app import Starbash, get_user_config_path, setup_logging
-from .commands import info, repo, select, user
+from .commands import info, process, repo, select, user
 from . import console
 
 app = typer.Typer(
@@ -17,6 +17,9 @@ app.add_typer(user.app, name="user", help="Manage user settings.")
 app.add_typer(repo.app, name="repo", help="Manage Starbash repositories.")
 app.add_typer(select.app, name="select", help="Manage session and target selection.")
 app.add_typer(info.app, name="info", help="Display system and data information.")
+app.add_typer(
+    process.app, name="process", help="Process images using automated workflows."
+)
 
 
 @app.callback(invoke_without_command=True)

starbash/paths.py

@@ -7,19 +7,24 @@ app_author = "geeksville"
 dirs = PlatformDirs(app_name, app_author)
 config_dir = Path(dirs.user_config_dir)
 data_dir = Path(dirs.user_data_dir)
+documents_dir = Path(dirs.user_documents_dir) / "starbash"
 
 # These can be overridden for testing
 _override_config_dir: Path | None = None
 _override_data_dir: Path | None = None
+_override_documents_dir: Path | None = None
 
 
 def set_test_directories(
-    config_dir_override: Path | None = None, data_dir_override: Path | None = None
+    config_dir_override: Path | None = None,
+    data_dir_override: Path | None = None,
+    documents_dir_override: Path | None = None,
 ) -> None:
     """Set override directories for testing. Used by test fixtures to isolate test data."""
-    global _override_config_dir, _override_data_dir
+    global _override_config_dir, _override_data_dir, _override_documents_dir
     _override_config_dir = config_dir_override
     _override_data_dir = data_dir_override
+    _override_documents_dir = documents_dir_override
 
 
 def get_user_config_dir() -> Path:
@@ -36,3 +41,14 @@ def get_user_data_dir() -> Path:
     dir_to_use = _override_data_dir if _override_data_dir is not None else data_dir
     os.makedirs(dir_to_use, exist_ok=True)
     return dir_to_use
+
+
+def get_user_documents_dir() -> Path:
+    """Get the user documents directory. Returns test override if set, otherwise the real user directory."""
+    dir_to_use = (
+        _override_documents_dir
+        if _override_documents_dir is not None
+        else documents_dir
+    )
+    os.makedirs(dir_to_use, exist_ok=True)
+    return dir_to_use

starbash/recipes/master_bias/starbash.toml

@@ -10,31 +10,37 @@ author.email = "FIXMESiril?"
 [[stage]]
 
 description = "Generate master bias"
-disabled = true # FIXME, debugging later stuff
+# disabled = false # turn on to skip
 
 # Restrict processing of this stage to only if detected hardware was found for this session
 # For any camera
-auto.for-camera = []
+# auto.for-camera = []
 
-tool = "siril"
+tool.name = "siril"
+# tool.timeout = 15.0 # allow up to 15 seconds before we timeout and kill tool
 
 # or auto?
 # find the most recent raw fits for the current instrument (as of the time of session start)
 # input.source = "most-recent" # only look for the most recent set of raws for this particular type
 input.type = "bias" # look in all raw repos, but look only for bias files
 
-# for early development we have support for simple absolute file paths with globs
-input.source = "path"
-input.path = "/workspaces/starbash/images/from_astroboy/masters-raw/2025-09-09/BIAS/*.fit*"
-input.required = true # Is at least one input file required?  If true, we will skip running this stage entirely (with a warning)
+# Look for files in input repos, finding them by using the "relative" tag they contain
+input.source = "repo"
+input.required = 2 # siril needs at least 2 frames to stack
+# old school paths also work (but are not recommended)
+# input.path = ".../from_astroboy/masters-raw/2025-09-09/BIAS/*.fit*"
 
-# make the following also work
-#
-#os.makedirs(os.path.dirname(output), exist_ok=True)
-#os.makedirs(os.path.dirname(process_dir), exist_ok=True)
-#frames = glob(f"{masters_raw}/{date}/BIAS/{date}_*.fit*")
-#siril_run_in_temp_dir(frames, ...
-when = "session-config" # run at the start of each session process
+when = "setup.master.bias" # run when master biases are regenerated
+
+# Based on the following definitions in the stage toml file...
+output.dest = "repo" # write to a particular repo
+output.type = "master" # write output to the special masters repo
+
+# the following fields will be auto populated in the context before entry:
+# context.output.base_path - the full filepath to write the output file to **excluding the suffix**
+# context.output.full_path - the full filepath to write the output file to (including suffix)
+# (NOT implemented / needed) context.output.root_path - points to the base of the destination repo
+# (NOT implemented / needed) context.output.suffix - the suffix to append to the output file (e.g. .fits or .fit.gz)
 
 # The following constants are auto defined before running the tool
 # context.process_dir (points to the session specific semi-persistent local dir for that sessions written/read data files)
@@ -42,14 +48,21 @@ when = "session-config" # run at the start of each session process
 # context.temp_dir (points to a temporary directory this tool can use for writing)
 
 # Everything in the constants dict will be predefined as named variables for use by the script
-context.date = "2025-09-09"  # FIXME - later find auto latest date with bias frames
-context.output = "{masters}/biases/{date}_stacked.fits" # if the output already exists processing will be skipped
+# context.date = "2025-09-0.9"  # FIXME - later find auto latest date with bias frames
+
+# output file will be place in the masters repo
+# if the output already exists processing will be skipped
+#
+# with a path like "{instrument}/{date}/{imagetyp}/{sessionconfig}.fits"
+# this path comes from master_repo.relative
+# context.output = "{output.root}/{instrument}/{date}/{imagetyp}/{sessionconfig}.fits"
+
 
 script = '''
     # Convert Bias Frames to .fit files
-    link bias -out={process_dir}
+    link frames -out={process_dir}
     cd {process_dir}
 
-    # Stack Bias Frames to bias_stacked.fit
-    stack bias rej 3 3 -nonorm -out={output}
+    # Stack frames
+    stack frames rej 3 3 -nonorm -out={output["base_path"]}
     '''

starbash/recipes/master_dark/starbash.toml

@@ -0,0 +1,36 @@
+
+[repo]
+kind = "recipe"
+
+
+[recipe]
+author.name = "FIXMESiril?"
+author.email = "FIXMESiril?"
+
+[[stage]]
+
+description = "Generate master dark"
+
+tool.name = "siril"
+tool.timeout = 30
+
+input.type = "dark"
+
+# Look for files in input repos, finding them by using the "relative" tag they contain
+input.source = "repo"
+input.required = 2    # siril needs at least 2 frames to stack
+
+when = "setup.master.dark" # run when master darks are regenerated
+
+# Based on the following definitions in the stage toml file...
+output.dest = "repo"   # write to a particular repo
+output.type = "master" # write output to the special masters repo
+
+script = '''
+    # Convert bias/dark Frames to .fit files
+    link frames -out={process_dir}
+    cd {process_dir}
+
+    # Stack frames
+    stack frames rej 3 3 -nonorm -out={output["base_path"]}
+    '''

starbash/recipes/master_flat/starbash.toml

@@ -10,26 +10,36 @@ author.email = "FIXMESiril?"
 
 [[stage]]
 
+# See master_bias/starbash.toml for more documentation
+
 description = "Generate master flat"
-disabled = true # FIXME, debugging later stuff
+# disabled = false
 
-# For any camera
-auto.for-camera = []
+tool.name = "siril"
+# tool.timeout = 15.0 # allow up to 15 seconds before we timeout and kill tool
 
-tool = "siril"
-# input.source = "session" # or auto? prefer ones in session otherwise find by in masters
-input.type = "flat" # look in _session_ directories, but look only for flat files
+# or auto?
+# find the most recent raw fits for the current instrument (as of the time of session start)
+# input.source = "most-recent" # only look for the most recent set of raws for this particular type
+input.type = "flat" # look in all raw repos, but look only for flat files
 
-# FIXME for early development we have support for simple absolute file paths with globs
-input.source = "path"
-input.path = "/workspaces/starbash/images/from_astroboy/M 27/2025-09-16/FLAT/*.fit*"
-input.required = true # Is at least one input file required?  If true, we will skip running this stage entirely (with a warning)
+# Look for files in input repos, finding them by using the "relative" tag they contain
+input.source = "repo"
+input.required = 2 # siril needs at least 2 frames to stack
+
+# We require a master bias frame for this recipe.  By the time our recipe is invoked
+# context.master.bias will have been set to a full path to a master bias frame
+input.masters = ["bias"]
 
-when = "session-config" # run once per session-config
-context.output = "{process_dir}/flat_s{sessionid}_c{sessionconfig}.fits"
+when = "setup.master.flat" # run when master biases are regenerated
 
-# FIXME, bias should have been added to context by two previous stages.  But for now hardwire
-context.bias = '/workspaces/starbash/images/masters/biases/2025-09-09_stacked.fits'
+# Based on the following definitions in the stage toml file...
+output.dest = "repo" # write to a particular repo
+output.type = "master" # write output to the special masters repo
+
+# FIXME for early development we have support for simple absolute file paths with globs
+#input.source = "path"
+#input.path = "/workspaces/starbash/images/from_astroboy/M 27/2025-09-16/FLAT/*.fit*"
 
 script = '''
     # Create a sequence from the raw flat frames
@@ -37,10 +47,10 @@ script = '''
     cd {process_dir}
 
     # Calibrate the flat frames using master bias
-    calibrate flat -bias={bias}
+    calibrate flat -bias={master["bias"]}
 
-    # Stack the pre-processed (calibrated) flat frames (writes to flat_stacked.fit)
-    stack pp_flat rej 3 3 -norm=mul -out=flat_stacked
+    # Stack the pre-processed (calibrated) flat frames
+    stack pp_flat rej 3 3 -norm=mul -out={output["base_path"]}
     '''
 
 temporaries = ["flat", "pp_flat"]

starbash/recipes/osc_dual_duo/starbash.py

@@ -4,6 +4,7 @@
 import os
 from glob import glob
 from starbash.tool import tools
+from starbash.aliases import normalize_target_name
 
 siril = tools["siril"]
 
@@ -18,11 +19,6 @@ def perhaps_delete_temps(temps: list[str]) -> None:
                 os.remove(path)
 
 
-def normalize_target_name(name: str) -> str:
-    """Converts a target name to an any filesystem-safe format by removing spaces"""
-    return name.replace(" ", "").upper()
-
-
 def make_stacked(sessionconfig: str, variant: str, output_file: str):
     """
     Registers and stacks all pre-processed light frames for a given filter configuration

starbash/recipes/osc_dual_duo/starbash.toml

@@ -30,8 +30,9 @@ auto.for-filter = ["SiiOiii"]
 # auto.for-filter = ["HaOiii"]
 auto.for-camera = ["OSC"]
 
-tool = "siril"
-when = "session-light" # run once per session-config
+tool.name = "siril"
+
+when = "session.light" # run once per session.config
 output = "FIXME"
 
 # FIXME, bias and flat should have been added to context by two previous stages.  But for now hardwire
@@ -74,8 +75,11 @@ description = "Stack OSC dual duo filter data, with separate Ha, Oiii and Sii ch
 context.target = "M 27" # FIXME
 context.targets = "/workspaces/starbash/images/processed" # FIXME, do something smarter
 
-tool = "python"
-when = "session-stack" # run once after all session/session-config processing was done
+tool.name = "python"
+
+when = "session.stack" # run once after all session/session.config processing was done
+
+input.masters = ["bias", "flat"]
 
 # if not specified starbash.py used
 # script-file = "script.py"

starbash/recipes/osc_single_duo/starbash.toml

@@ -23,8 +23,8 @@ disabled = true # FIXME, we don't yet have auto selection based on filter types
 auto.for-filter = ["HaOiii"]
 auto.for-camera = ["OSC"]
 
-tool = "siril"
-when = "session-light" # run once per session-config
+tool.name = "siril"
+when = "session.light" # run once per session.config
 output = "FIXME"
 
 script = '''
@@ -45,8 +45,8 @@ temporaries = ["FIXME"]
 
 disabled = true # FIXME, we don't yet have auto selection based on filter types
 
-tool = "python"
-when = "session-stack" # run once after all session/session-config processing was done
+tool.name = "python"
+when = "session.stack" # run once after all session/session.config processing was done
 
 script-file = "script.py"
 

starbash/recipes/starbash.toml

@@ -5,6 +5,8 @@ kind = "repo"
 [[repo-ref]]
 dir = "master_bias"
 [[repo-ref]]
+dir = "master_dark"
+[[repo-ref]]
 dir = "master_flat"
 
 # Note: For automated recipe finding, it is important to list more demanding recipes first.  For instance:
@@ -21,14 +23,37 @@ dir = "osc_single_duo"
 
 # processing stages, currently all declared here, but possibly in the future they could be added by user/other toml files
 
+# Not included in standard list - for now we run manually
+#[[stages]]
+#name = "setup-masters" # for flat processing, master generation etc
+#priority = 5
+
+#
+# master specific stages
+#
+[[master-stages]]
+name = "setup.master.bias" # generate master bias frames
+priority = 10
+
+[[master-stages]]
+name = "setup.master.dark" # generate master bias frames
+priority = 10
+
+[[master-stages]]
+name = "setup.master.flat" # generate master flat frames
+priority = 20
+
+#
+# session specific processing stages
+#
 [[stages]]
-name = "session-config" # for flat processing, master generation etc
+name = "session.config" # for flat processing, master generation etc
 priority = 10
 
 [[stages]]
-name = "session-light" # generate light frames from lights and with reference to flats/bias
+name = "session.light" # generate light frames from lights and with reference to flats/bias
 priority = 20
 
 [[stages]]
-name = "session-stack" # stack frames
+name = "session.stack" # stack frames
 priority = 30

starbash/selection.py

@@ -2,11 +2,58 @@
 
 from __future__ import annotations
 
-import json
 import logging
-from pathlib import Path
-from typing import Any, Optional
-from datetime import datetime
+from typing import Any, Optional, TYPE_CHECKING
+from repo import Repo
+from starbash.aliases import normalize_target_name
+
+
+def where_tuple(conditions: dict[str, Any] | None) -> tuple[str, list[Any]]:
+    """Search for sessions matching the given conditions.
+
+    Args:
+        conditions: Dictionary of session key-value pairs to match, or None for all.
+                    Special keys:
+                    - 'date_start': Filter sessions starting on or after this date
+                    - 'date_end': Filter sessions starting on or before this date
+
+    Returns:
+        Tuple of (WHERE clause string, list of parameters)
+    """
+    if conditions is None:
+        conditions = {}
+
+    # Build WHERE clause dynamically based on conditions
+    where_clauses = []
+    params = []
+
+    # Extract date range conditions
+    date_start = conditions.get("date_start")
+    date_end = conditions.get("date_end")
+
+    # Add date range filters to WHERE clause
+    if date_start:
+        where_clauses.append("start >= ?")
+        params.append(date_start)
+
+    if date_end:
+        where_clauses.append("start <= ?")
+        params.append(date_end)
+
+    # Add standard conditions to WHERE clause
+    for key, value in conditions.items():
+        if key not in ("date_start", "date_end") and value is not None:
+            column_name = key
+            where_clauses.append(f"{column_name} = ?")
+            params.append(value)
+
+    # Build the query
+    query = ""
+
+    if where_clauses:
+        query += " WHERE " + " AND ".join(where_clauses)
+
+    return (query, params)
 
 
 class Selection:
@@ -19,16 +66,17 @@ class Selection:
     - Image types
     - Telescope names
 
-    The selection state is saved to disk and can be used to build database queries.
+    The selection state is saved to the user config repo TOML file and can be
+    used to build database queries.
     """
 
-    def __init__(self, state_file: Path):
-        """Initialize the Selection with a state file path.
+    def __init__(self, user_repo: "Repo"):
+        """Initialize the Selection with the user config repository.
 
         Args:
-            state_file: Path to the JSON file where selection state is persisted
+            user_repo: The Repo object for user preferences where selection state is persisted
         """
-        self.state_file = state_file
+        self.user_repo = user_repo
         self.targets: list[str] = []
         self.date_start: Optional[str] = None
         self.date_end: Optional[str] = None
@@ -40,39 +88,59 @@ class Selection:
         self._load()
 
     def _load(self) -> None:
-        """Load selection state from disk."""
-        if self.state_file.exists():
-            try:
-                with open(self.state_file, "r") as f:
-                    data = json.load(f)
-                    self.targets = data.get("targets", [])
-                    self.date_start = data.get("date_start")
-                    self.date_end = data.get("date_end")
-                    self.filters = data.get("filters", [])
-                    self.image_types = data.get("image_types", [])
-                    self.telescopes = data.get("telescopes", [])
-                logging.debug(f"Loaded selection state from {self.state_file}")
-            except Exception as e:
-                logging.warning(f"Failed to load selection state: {e}")
+        """Load selection state from user config repo."""
+        try:
+            # Load with type-safe defaults
+            targets = self.user_repo.get("selection.targets", [])
+            self.targets = targets if isinstance(targets, list) else []
+
+            self.date_start = self.user_repo.get("selection.date_start")
+            self.date_end = self.user_repo.get("selection.date_end")
+
+            filters = self.user_repo.get("selection.filters", [])
+            self.filters = filters if isinstance(filters, list) else []
+
+            image_types = self.user_repo.get("selection.image_types", [])
+            self.image_types = image_types if isinstance(image_types, list) else []
+
+            telescopes = self.user_repo.get("selection.telescopes", [])
+            self.telescopes = telescopes if isinstance(telescopes, list) else []
+
+            logging.debug(f"Loaded selection state from {self.user_repo.url}")
+        except Exception as e:
+            logging.warning(f"Failed to load selection state: {e}")
 
     def _save(self) -> None:
-        """Save selection state to disk."""
+        """Save selection state to user config repo."""
         try:
-            # Ensure parent directory exists
-            self.state_file.parent.mkdir(parents=True, exist_ok=True)
-
-            data = {
-                "targets": self.targets,
-                "date_start": self.date_start,
-                "date_end": self.date_end,
-                "filters": self.filters,
-                "image_types": self.image_types,
-                "telescopes": self.telescopes,
-            }
-
-            with open(self.state_file, "w") as f:
-                json.dump(data, f, indent=2)
-            logging.debug(f"Saved selection state to {self.state_file}")
+            self.user_repo.set("selection.targets", self.targets)
+
+            # Handle date fields - set if not None, delete if None (to clear them)
+            if self.date_start is not None:
+                self.user_repo.set("selection.date_start", self.date_start)
+            else:
+                # Delete the key if it exists
+                if "selection" in self.user_repo.config:
+                    sel_section = self.user_repo.config["selection"]
+                    if isinstance(sel_section, dict) and "date_start" in sel_section:
+                        del sel_section["date_start"]  # type: ignore
+
+            if self.date_end is not None:
+                self.user_repo.set("selection.date_end", self.date_end)
+            else:
+                # Delete the key if it exists
+                if "selection" in self.user_repo.config:
+                    sel_section = self.user_repo.config["selection"]
+                    if isinstance(sel_section, dict) and "date_end" in sel_section:
+                        del sel_section["date_end"]  # type: ignore
+
+            self.user_repo.set("selection.filters", self.filters)
+            self.user_repo.set("selection.image_types", self.image_types)
+            self.user_repo.set("selection.telescopes", self.telescopes)
+
+            # Write the updated config to disk
+            self.user_repo.write_config()
+            logging.debug(f"Saved selection state to {self.user_repo.url}")
         except Exception as e:
             logging.error(f"Failed to save selection state: {e}")
 
@@ -174,14 +242,11 @@ class Selection:
             and not self.telescopes
         )
 
-    def get_query_conditions(self) -> dict[str, Any]:
+    def get_query_conditions(self) -> tuple[str, list[Any]]:
         """Build query conditions based on the current selection.
 
         Returns:
-            Dictionary of query conditions that can be used with Database methods.
-            Special keys:
-            - 'date_start': ISO date string for start of range
-            - 'date_end': ISO date string for end of range
+            A tuple of SQL (WHERE clause string, list of parameters)
         """
         conditions = {}
 
@@ -192,7 +257,11 @@ class Selection:
         if self.targets:
             # For now, just use the first target
             # TODO: Support multiple targets in queries
-            conditions["OBJECT"] = self.targets[0] if len(self.targets) == 1 else None
+            conditions["OBJECT"] = (
+                normalize_target_name(self.targets[0])
+                if len(self.targets) == 1
+                else None
+            )
 
         if self.filters:
             # For now, just use the first filter
@@ -212,7 +281,7 @@ class Selection:
         if self.date_end:
             conditions["date_end"] = self.date_end
 
-        return conditions
+        return where_tuple(conditions)
 
     def summary(self) -> dict[str, Any]:
         """Get a summary of the current selection state.

starbash/templates/repo/master.toml

@@ -0,0 +1,13 @@
+# This is a master repository for (Starbash)[{PROJECT_URL}].
+#
+# This file marks the root directory of a set of auto matinained astrophotography
+# 'master' files, such as master darks, flats or biases.
+#
+# You generally don't need to edit this file directly - it was auto generated when you ran
+# "sb repo add --master {REPO_PATH}".
+#
+
+[repo]
+kind = "master"
+
+relative = "{DEFAULT_RELATIVE}"

starbash/templates/repo/processed.toml

@@ -0,0 +1,10 @@
+# This is a processed repository for (Starbash)[{PROJECT_URL}].
+#
+# This file marks the root directory of a set of generated/processed starbash output files.
+#
+# You generally don't need to edit this file directly - it was auto generated when you ran
+# "sb repo add --processed {REPO_PATH}".
+#
+
+[repo]
+kind = "processed"

starbash/templates/userconfig.toml

@@ -1,4 +1,4 @@
-# This is your Starbash user configuration file.  It can be used to provide default settings
+# This is your (Starbash)[{PROJECT_URL}] user configuration file.  It can be used to provide default settings
 # to workflows.
 
 # (or wherever is appropriate for the user's platform).