astro-subframe-organizer 0.0.2

data/lib/astro_subframe_organizer/filename_parsers/cr2_filename_parser.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module FilenameParsers
+    # Parser for Canon CR2 (Canon Raw 2) format files from ASIAir Plus.
+    #
+    # CR2 files are Canon RAW image files that can be captured by cameras like the Canon T7.
+    # The filename structure is similar to FITS files when captured via ASIAir Plus.
+    #
+    # Expected filename format:
+    #   Type_[Target]_[Mosaic]_Exposure_BinBinning_Camera_ISO/Gain_DateTime_CCDTemp_ImageIndex.cr2
+    #
+    # Example:
+    #   Light_M42_1.0s_Bin1_T7_ISO100_20220508-120000_-10.0C_0001.cr2
+    #
+    # Returns a hash with keys identical to FitsFilenameParser, except:
+    #   - :file_format (:cr2 instead of :fits)
+    #
+    # The CR2 format uses CCD-TEMP instead of ISO for temperature tracking since RAW files
+    # preserve more metadata from the camera hardware.
+    class CR2FilenameParser < FilenameParser
+      include Logging
+
+      # @return [Hash] Parsed metadata from CR2 filename
+      def parse # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        base_name = extract_base_name
+        parts = parse_parts(base_name)
+        result = {}
+
+        if @filename.start_with? 'IMG_'
+          logger.error(
+            'Raw images must be renamed before organizing. Run `astro-subframe-organizer raw rename`, ' \
+            'then try again.',
+          )
+          exit(1)
+        end
+
+        begin
+          result[:file_format] = :cr2
+          result[:path] = @path
+          result[:filename] = @filename
+
+          # If the file is already organized somewhere, get the information from its path.
+          result.merge!(extract_metadata_from_path)
+
+          result[:type] = parts.shift
+          result[:target] = parts.shift if result[:type] == 'Light'
+          result[:mosaic_pane] = parts.shift if parts.first&.match?(/\A\d+-\d+\z/)
+          result[:exposure] = parts.shift
+          result[:bin] = parts.shift.gsub('Bin', '') if parts.first&.start_with?('Bin')
+          result[:camera] = parts.shift if Equipment::Camera.all.include?(parts.first)
+          result[:iso] = parts.shift.gsub('ISO', '') if parts.first&.start_with?('ISO')
+          result[:gain] = parts.shift.gsub('gain', '') if parts.first&.start_with?('gain')
+          result[:created_at] = DateTime.strptime(parts.shift, FILENAME_DT_FORMAT)
+          result[:ccd_temp] = parts.shift
+          result[:image_index] = parts.shift
+        rescue StandardError => e
+          logger.error "Failed to parse #{@path}: #{e}"
+        ensure
+          logger.debug result
+        end
+
+        FileMetadata.from_parsed_data(result)
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/filename_parsers/fits_filename_parser.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module FilenameParsers
+    # Parser for FITS format files from ASIAir Plus.
+    #
+    # Expected filename format:
+    #   Type_[Target]_[Mosaic]_Exposure_BinBinning_Camera_ISO/Gain_DateTime_CCDTemp_ImageIndex
+    #
+    # Example:
+    #   Light_M42_1.0s_Bin1_T7_ISO100_20220508-120000_-10.0C_0001.fit
+    #   Dark_30.0s_Bin1_T7_ISO100_20220508-120000_-10.0C_0001.fit
+    #
+    # Returns a hash with keys:
+    #   - :type (Light, Dark, Flat, Bias)
+    #   - :target (for Light files only)
+    #   - :mosaic_pane (optional, if present)
+    #   - :exposure (with units, e.g., "1.0s")
+    #   - :bin (numeric string)
+    #   - :camera (model name)
+    #   - :iso (numeric string, if present)
+    #   - :gain (numeric string, if ISO not present)
+    #   - :created_at (DateTime object)
+    #   - :ccd_temp (with units, e.g., "-10.0C")
+    #   - :image_index (numeric string)
+    #   - :file_format (:fits)
+    #   - :path (full file path)
+    #   - :filename (just the filename)
+    class FitsFilenameParser < FilenameParser
+      include Logging
+
+      # @return [Hash] Parsed metadata from FITS filename
+      def parse # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        base_name = extract_base_name
+        parts = parse_parts(base_name)
+        result = {}
+
+        begin
+          result[:file_format] = :fits
+          result[:path] = @path
+          result[:filename] = @filename
+
+          # If the file is already organized somewhere, get the information from its path.
+          result.merge!(extract_metadata_from_path)
+
+          result[:type] = parts.shift
+          result[:target] = parts.shift if result[:type] == 'Light'
+          result[:mosaic_pane] = parts.shift if parts.first&.match?(/\A\d+-\d+\z/)
+          result[:exposure] = parts.shift
+          result[:bin] = parts.shift.gsub('Bin', '') if parts.first&.start_with?('Bin')
+          result[:camera] = parts.shift if Equipment::Camera.all.include?(parts.first)
+          result[:iso] = parts.shift.gsub('ISO', '') if parts.first&.start_with?('ISO')
+          result[:gain] = parts.shift.gsub('gain', '') if parts.first&.start_with?('gain')
+          result[:created_at] = DateTime.strptime(parts.shift, FILENAME_DT_FORMAT)
+          result[:ccd_temp] = parts.shift
+          result[:image_index] = parts.shift
+        rescue StandardError => e
+          logger.error e
+        ensure
+          logger.debug result
+        end
+
+        FileMetadata.from_parsed_data(result)
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/filename_parsers/fits_header_parser.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'fits_parser'
+
+module AstroSubframeOrganizer
+  module FilenameParsers
+    # Parser to generate FileMetadata based on FITS headers and filename patterns.
+    class FitsHeaderParser < FilenameParser
+      include Logging
+      include AstroSubframeOrganizer::Utils::ExposureFormat
+
+      def headers
+        @headers ||= load_headers(path)
+      end
+
+      def [](key)
+        headers[key]
+      end
+
+      def parse # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        result = {
+          file_format: :fits,
+          path: @path,
+          filename: @filename,
+        }
+
+        # If the file is already organized somewhere, get the information from its path.
+        metadata_from_path = extract_metadata_from_path
+        result[:telescope] = metadata_from_path[:telescope] || header(:telescope)
+        result[:filter]    = metadata_from_path[:filter]    || header(:filter)
+        result[:dark_flat] = metadata_from_path[:dark_flat]
+
+        result[:type]        = image_type
+        result[:target]      = target if light_frame?
+        result[:exposure]    = format_exposure(header(:exposure))
+        result[:bin]         = header(:binning)
+        result[:camera]      = header(:camera)
+        result[:gain]        = header(:gain)
+        result[:iso]         = header(:iso)
+        result[:created_at]  = parse_date(header(:date_obs))
+        result[:ccd_temp]    = format_temp(ccd_temperature)
+        result[:image_index] = parse_parts(extract_base_name).last
+        result[:rotation]    = rotation_angle
+        result[:mosaic_pane] = mosaic_pane
+
+        FileMetadata.from_parsed_data(result)
+      rescue StandardError => e
+        logger.error "Failed to parse FITS headers for #{@filename}: #{e.message}"
+        FileMetadata.from_parsed_data(file_format: :fits, path: @path, filename: @filename)
+      ensure
+        logger.debug result
+      end
+
+      def target
+        header(:target) || parsed_from_filename[:target]
+      end
+
+      def mosaic_pane
+        # Not available in FITS headers for ASIAIR mosaic frames.
+        # Must be parsed from filename pattern: TARGET_ROW-COL_
+        parsed_from_filename[:mosaic_pane]
+      end
+
+      def image_type
+        header(:type)
+      end
+
+      def light_frame?
+        image_type == Astrophoto::LIGHT
+      end
+
+      def header(key)
+        keys = Config.fits_header_mappings[key.to_s] || []
+        keys.lazy.filter_map { |k| headers[k] }.first
+      end
+
+      def rotation_angle
+        header(:rotation)
+      end
+
+      def ccd_temperature
+        header(:temperature)
+      end
+
+      private
+
+      def load_headers(path)
+        hdu = FitsParser.open(path) do |parser|
+          parser.parse_hdus.find { |h| h[:header] }
+        end
+        raise "No HDU with headers found in #{path}" unless hdu
+
+        hdu[:header]
+      end
+
+      def parse_date(value)
+        return nil if value.nil?
+
+        DateTime.strptime(value, '%Y-%m-%dT%H:%M:%S.%6N')
+      rescue ArgumentError
+        DateTime.parse(value)
+      end
+
+      def parsed_from_filename
+        @parsed_from_filename ||= begin
+          parts = File.basename(@path, '.*').split('_')
+          pane_index = parts.index { |p| p.match?(/\A\d{1,2}-\d{1,2}\z/) }
+          {
+            target: pane_index ? parts[1...pane_index].join('_') : nil,
+            mosaic_pane: pane_index ? parts[pane_index] : nil,
+          }
+        end
+      end
+
+      def format_temp(temp)
+        format '%0.1fC', temp
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/fits_organizer.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  # Main class responsible for interactively organizing FITS files based on their headers and user input.
+  class FitsOrganizer
+    include Logging
+
+    private attr_accessor :prompt, :path, :dry_run
+
+    def initialize(path = Dir.pwd, dry_run: nil)
+      self.prompt = AstroSubframeOrganizer.prompt
+      self.path = path
+      self.dry_run = dry_run
+    end
+
+    # Organizes dark files by ISO, BIN, CCD-TEMP, EXPOSURE, and MONTH to facilitate the creation of
+    # master darks that may have varying temperatures. This organization can be changed by updating
+    # Astrophoto#target_dir for the DARK type.
+    #
+    # If the file has an exposure of less than 10 seconds, you will be asked if it is a flat dark.
+    # If so, it will be organized into a folder that will match your corresponding flat files so that
+    # you can run WBPP with just your biases, flat darks, and flats using the grouping keywords
+    # FLATSET, BIN, EXP, and ISO. CCD-TEMP will be ignored for the purposes of these files, as it is
+    # assumed they will be taken under roughly the same conditions as the flats are taken.
+    #
+    # If the files are normal dark files, they will be organized by ISO, EXPOSURE, BIN, CCD-TEMP, and MONTH.
+    # With this, you can run WBPP with just bias and darks using the grouping keywords CCD-TEMP, ISO, EXP,
+    # and MONTH (optional).
+    def organize_darks
+      Organizer.new(
+        path: path,
+        type: Astrophoto::DARK,
+        prompt: prompt,
+      ).organize(dry_run: is_dry_run?)
+    end
+
+    def organize_biases
+      Organizer.new(
+        path: path,
+        type: Astrophoto::BIAS,
+        prompt: prompt,
+      ).organize(dry_run: is_dry_run?)
+    end
+
+    # Organizes flat files by FLATSET, ISO, BIN, EXP (EXPOSURE), TELESCOPE, and FILTER. To change these
+    # properties, update Astrophoto#target_dir for the FLAT type. The TELESCOPE and FILTER keywords are
+    # for matching LIGHTS which will have the same keywords set when organized using this script.
+    #
+    # You can run WBPP with just your biases, flat darks, and flats using the grouping keywords
+    # FLATSET, BIN, EXP, and ISO. CCD-TEMP will be ignored for the purposes of these files, as it is
+    # assumed they will be taken under roughly the same conditions as the flat darks are taken.
+    #
+    # After running WBPP, you should delete the `EXP` keyword from the master flat file name (if present)
+    # before using that master flat in a WBPP integration run, since exposure time should not be considered
+    # when grouping flats to lights.
+    def organize_flats
+      Organizer.new(
+        path: path,
+        type: Astrophoto::FLAT,
+        prompt: prompt,
+      ).organize(dry_run: is_dry_run?)
+    end
+
+    # Organizes light files by FLATSET, ISO, BIN, EXP (EXPOSURE), TELESCOPE, and FILTER. To change these
+    # properties, update Astrophoto#target_dir for the LIGHT type. The TELESCOPE and FILTER keywords are
+    # for matching LIGHTS which will have the same keywords set when organized using this script.
+    #
+    # CCD-TEMP is included in the group naming using a rounded value to facilitate consistent keyword matching
+    # in PixInsight WBPP, ensuring frames captured within a temperature range are grouped together.
+    #
+    # You can run WBPP with just your master biases, master darks, and master flats using the grouping
+    # keywords FLATSET, BIN, EXP, CCD-TEMP, and ISO.
+    #
+    # If you are running WBPP on multiple targets using this data, e.g. for a mosaic, you should make sure
+    # to use LIGHT as a post-processing keyword and register files using `auto by LIGHT`.
+    def organize_lights
+      Organizer.new(
+        path: path,
+        type: Astrophoto::LIGHT,
+        prompt: prompt,
+      ).organize(dry_run: is_dry_run?)
+    end
+
+    # Checks for empty directories. Run this option after performing a move of previously
+    # organized data.
+    def remove_empty_directories
+      Utils::EmptyDirectoryCleaner.new(path).cleanup(dry_run: is_dry_run?)
+    end
+
+    # Removes all the jpg thumbnails under this directory.
+    def remove_jpg_thumbnails
+      Utils::ThumbnailCleaner.new(path).cleanup(dry_run: is_dry_run?)
+    end
+
+    # Renames CR2 Raw files to match the same name pattern as ASIAir does based on EXIF data.
+    def rename_from_exif
+      renamer = Utils::ExifRenamer.new(path)
+      type = prompt.enum_select('What is the file type?', Astrophoto::TYPES)
+      target = prompt.ask('What is the target name?') if type == Astrophoto::LIGHT
+
+      renamer.rename(type: type, target: target, dry_run: is_dry_run?)
+    end
+
+    def is_dry_run? # rubocop:disable Naming/PredicatePrefix
+      dry_run.nil? ? prompt.yes?('Is this a dry run?', default: 'y') : dry_run
+    end
+
+    def rename_to_img
+      renamer = Utils::ExifRenamer.new(path)
+      renamer.revert(dry_run: is_dry_run?)
+    end
+
+    # Prompts the user to choose which organizing task to run. This is the main entry point of
+    # this script.
+    def organize
+      loop do
+        message = 'What are we organizing?'
+        message += ' (Dry Run)' if dry_run
+
+        choice = prompt.enum_select message, per_page: 8 do |menu|
+          menu.choice 'Darks', :darks
+          menu.choice 'Flats', :flats
+          menu.choice 'Lights', :lights
+          menu.choice 'Biases', :biases
+          menu.choice 'Remove empty directories', :empty_dirs
+          menu.choice 'Remove jpg thumbnails', :thumbnails
+          menu.choice 'Rename files from EXIF data', :rename
+          menu.choice 'Quit', :quit
+        end
+
+        case choice
+        when :darks      then organize_darks
+        when :flats      then organize_flats
+        when :lights     then organize_lights
+        when :biases     then organize_biases
+        when :empty_dirs then remove_empty_directories
+        when :thumbnails then remove_jpg_thumbnails
+        when :rename     then rename_from_exif
+        when :quit       then break
+        end
+      end
+    end
+
+    def self.run
+      organizer = FitsOrganizer.new
+      organizer.organize
+    end
+
+    private
+
+    # TODO: Add menu to select for barlow/flatteners
+    def select_accessories; end
+  end
+end

data/lib/astro_subframe_organizer/logging.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  # Mixin to provide logging capabilities to classes in the AstroSubframeOrganizer module.
+  module Logging
+    def logger
+      AstroSubframeOrganizer.logger
+    end
+  end
+end

data/lib/astro_subframe_organizer/organizer.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  # Main class responsible for organizing astrophotography subframes based on metadata and user input.
+  class Organizer
+    include Logging
+
+    attr_reader :file_sets, :type, :path, :equipment_selector
+    protected attr_accessor :prompt
+
+    def initialize(type:, path: Dir.pwd, prompt: AstroSubframeOrganizer.prompt, equipment_selector: nil)
+      @prompt = prompt
+      @path = path
+      @type = type
+      @file_sets = file_sets_for(type)
+      @equipment_selector = equipment_selector || EquipmentSelector.new(prompt)
+    end
+
+    def fits_files # rubocop:disable Metrics/AbcSize
+      exts = (Config.fits_extensions + Config.raw_extensions).flat_map { |e| [e.downcase, e.upcase] }
+      all = Dir.glob(exts.map { |e| "**/*#{e}" }, base: path)
+      processable = all.filter { |f| !File.basename(f).match?(Utils::ExifRenamer::RAW_NAME_PATTERN) }
+                       .uniq
+                       .map { |relative| File.join(path, relative) }
+
+      if processable.size != all.size
+        unprocessable_raw_files_warning = 'Unprocessed raw images detected, but will be ignored. " +
+        "Raw images must be renamed before organizing. Run `astro-subframe-organizer raw rename_from_exif`, " +
+        "then try again.'
+        logger.warn(unprocessable_raw_files_warning)
+      end
+
+      processable.map { |f| Astrophoto.new(f) }
+    end
+
+    def organize(dry_run: false) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      logger.info "Preparing to move #{file_sets.sum { |set| set.files.size }} #{type} files " \
+                  "from #{file_sets.size} groups..."
+      @file_sets.each do |fileset|
+        next if fileset.already_moved?
+
+        if fileset.all_unmoved?
+          move = ENV['ASTRO_SUBFRAME_SKIP_CONFIRM'] == 'true' ||
+                 prompt.yes?(
+                   <<~MSG,
+                     Preparing to move #{fileset.size} #{fileset.type} file(s)
+                        FROM #{relative_to_pwd(fileset.current_dir)}
+                        TO   #{relative_to_pwd(fileset.files.first.target_dir)}
+                     Continue?
+                   MSG
+                   default: 'y',
+                 )
+          next unless move
+        end
+
+        logger.info "For #{type} set #{fileset.files.first.filename}..#{fileset.files.last.filename}:"
+
+        check_telescope(fileset) if [Astrophoto::FLAT, Astrophoto::LIGHT].include?(type)
+        check_filter(fileset) if [Astrophoto::FLAT, Astrophoto::LIGHT].include?(type)
+        check_camera(fileset)
+
+        require 'tty-progressbar'
+
+        # Initialize the bar with the size of the fileset
+        bar = TTY::ProgressBar.new('Moving files [:bar] :current/:total (:percent) :eta', total: fileset.size)
+
+        fileset.each do |file|
+          file.move(dry_run, bar)
+          bar.advance(1) # Move the bar forward by 1 for each file
+        end
+
+        logger.info 'Done'
+      end
+    end
+
+    private
+
+    def file_sets_for(type)
+      FileSet.from_files(fits_files, type: type)
+    end
+
+    def check_camera(fileset)
+      candidates = fileset.camera_candidates
+      camera = if candidates.size > 1
+                 logger.warn "Multiple cameras detected: #{candidates}"
+                 equipment_selector.choose_camera
+               else
+                 equipment_selector.choose_camera_or_confirm(detected: candidates.first)
+               end
+
+      fileset.apply_camera!(camera)
+    end
+
+    def check_telescope(fileset)
+      candidates = fileset.telescope_candidates
+      telescope = if candidates.size > 1
+                    logger.warn "Multiple telescopes detected: #{candidates}"
+                    equipment_selector.choose_telescope
+                  else
+                    equipment_selector.choose_telescope_or_confirm(detected: candidates.first)
+                  end
+
+      fileset.apply_telescope!(telescope)
+    end
+
+    def check_filter(fileset)
+      candidates = fileset.filter_candidates
+      filter = if candidates.size > 1
+                 logger.warn "Multiple filters detected: #{candidates}"
+                 equipment_selector.choose_filter
+               else
+                 equipment_selector.choose_filter_or_confirm(detected: candidates.first)
+               end
+
+      fileset.apply_filter!(filter)
+    end
+
+    def relative_to_pwd(path)
+      relative = Pathname.new(path).relative_path_from(Dir.pwd).to_s
+      relative.start_with?('..') ? path : relative
+    rescue ArgumentError
+      path # fallback to absolute path on different drives (Windows)
+    end
+  end
+end

data/lib/astro_subframe_organizer/path_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  # Factory for creating and using path builders.
+  #
+  # This class serves as the entry point for building folder paths for astrophotography
+  # image files. It uses the Strategy pattern to delegate path construction to specialized
+  # builder classes based on the image file type (Dark, Flat, Light, or Bias).
+  #
+  # The resulting folder paths contain keywords that facilitate automatic file matching in
+  # PixInsight's WeightedBatchPreProcessing (WBPP) script during calibration and integration.
+  #
+  # **Usage:**
+  #   path = PathBuilder.build_for(photo_metadata)        # => "Dark_ISO_100_EXP_30.0s_..."
+  #   full_path = PathBuilder.target_path_for(metadata)   # => "Dark_ISO_100_.../filename.fit"
+  #
+  # See the individual builder classes for details on keyword structure for each file type:
+  # - DarkPathBuilder for dark calibration frames
+  # - FlatPathBuilder for flat field frames
+  # - LightPathBuilder for science (light) frames
+  # - BiasPathBuilder for bias (zero-exposure) frames
+  #
+  # See README.md for details on the WBPP calibration workflow and keyword matching.
+  class PathBuilder
+    # Builds the folder path for an image based on its type and metadata.
+    #
+    # @param metadata [Object] Image metadata object (typically an Astrophoto instance)
+    #                  Must respond to: type, dark_flat?, file_format
+    # @return [String] The folder path with WBPP-compatible keywords
+    # @raise [ArgumentError] If the image type is not supported
+    def self.build_for(metadata)
+      builder = case metadata.type
+                when 'Dark'
+                  PathBuilders::DarkPathBuilder.new(metadata)
+                when 'Flat'
+                  PathBuilders::FlatPathBuilder.new(metadata)
+                when 'Light'
+                  PathBuilders::LightPathBuilder.new(metadata)
+                when 'Bias'
+                  PathBuilders::BiasPathBuilder.new(metadata)
+                else
+                  raise ArgumentError, "Unsupported type: #{metadata.type}"
+                end
+      builder.build
+    end
+
+    # Builds the full target path (folder + filename) for an image.
+    #
+    # @param metadata [Object] Image metadata object with filename and type
+    # @return [String] The full path where the file will be moved
+    def self.target_path_for(metadata)
+      File.join(build_for(metadata), metadata.filename)
+    end
+  end
+end

data/lib/astro_subframe_organizer/path_builders/base_path_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module PathBuilders
+    # Base class for all path builders.
+    #
+    # Path builders construct folder paths based on image metadata, using keywords that
+    # facilitate organization for PixInsight's WeightedBatchPreProcessing (WBPP) script.
+    # WBPP uses these keywords to automatically match and group images for calibration and
+    # integration tasks.
+    #
+    # Subclasses should implement a `build` method that returns the folder path as a string
+    # with keyword-value pairs separated by underscores (e.g., "Dark_ISO_100_EXP_30.0s_...").
+    #
+    # See README.md for details on how WBPP uses these keywords in the calibration workflow.
+    class BasePathBuilder
+      def initialize(metadata)
+        @metadata = metadata
+      end
+
+      protected
+
+      # @return [String, nil] "ISO_<value>" if iso is present, "GAIN_<value>" if gain is present
+      def iso_or_gain
+        if @metadata.iso
+          "ISO_#{@metadata.iso}"
+        elsif @metadata.gain
+          "GAIN_#{@metadata.gain}"
+        end
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/path_builders/bias_path_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module PathBuilders
+    # Builds folder paths for bias (zero-exposure) calibration frames.
+    #
+    # Bias frames are organized by the following keywords, which allow WBPP to
+    # automatically match biases during calibration of darks, flats, and lights:
+    #
+    #   Bias_ISO_<value>_EXP_<value>_Bin_<value>_CAMERA_<model>_MONTH_<YYYY-MM>
+    #
+    # **Keyword meanings:**
+    # - ISO: Camera ISO setting
+    # - EXP: Exposure time (typically 0.0s for bias frames)
+    # - Bin: Binning mode
+    # - CAMERA: Camera model
+    # - MONTH: Year-Month in YYYY-MM format (used for seasonal grouping)
+    #
+    # Bias frames are primarily used as the baseline calibration for darks, flats, and lights
+    # to remove electronic noise. WBPP uses these keywords to match an appropriate master bias
+    # based on the ISO, exposure, binning, and season of acquisition.
+    #
+    # See README.md for details on the WBPP calibration workflow.
+    class BiasPathBuilder < BasePathBuilder
+      # @return [String] The folder path for this bias frame
+      def build
+        [
+          'Bias',
+          iso_or_gain,
+          "EXP_#{@metadata.exposure}",
+          "Bin_#{@metadata.bin}",
+          "CAMERA_#{@metadata.camera || '????'}",
+          "MONTH_#{@metadata.month}",
+        ].compact.join('_')
+      end
+    end
+  end
+end