astro-subframe-organizer 0.0.2

data/lib/astro_subframe_organizer/path_builders/dark_path_builder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module PathBuilders
+    # Builds folder paths for dark calibration frames.
+    #
+    # Dark frames are organized into folders by the following keywords, which allow WBPP
+    # to automatically match darks to lights during calibration:
+    #
+    # **Normal Darks:**
+    #   - Dark_ISO_<value>_EXP_<value>_CCD-TEMP_<value>_CAMERA_<model>_MONTH_<YYYY-MM>
+    #
+    #   These keywords enable matching darks to lights based on ISO, exposure time, CCD
+    #   temperature, and the season (month) when captured. Temperature matching in WBPP
+    #   allows for +/- 1°C variation to accommodate uncooled cameras.
+    #
+    # **Flat Darks (short exposure darks < 10 seconds):**
+    #   - DarkFlat_FLATSET_<date>_ISO_<value>_EXP_<value>_Bin_<value>_CAMERA_<model>
+    #
+    #   Flat darks are grouped with their corresponding flat set using the FLATSET keyword.
+    #   Temperature is not included since flats and flat darks are captured at roughly the
+    #   same time under similar conditions. These are organized together so WBPP can load
+    #   them as a unit during the flat field calibration step.
+    #
+    # See README.md for details on WBPP_Darks and WBPP_Flats process icons.
+    class DarkPathBuilder < BasePathBuilder
+      # @return [String] The folder path for this dark frame
+      def build
+        if @metadata.dark_flat?
+          build_flat_dark_path
+        else
+          build_normal_dark_path
+        end
+      end
+
+      private
+
+      def build_normal_dark_path
+        [
+          'Dark',
+          iso_or_gain,
+          "EXP_#{@metadata.exposure}",
+          "CCD-TEMP_#{@metadata.rounded_ccd_temp}",
+          "CAMERA_#{@metadata.camera || '????'}",
+          "MONTH_#{@metadata.month}",
+        ].compact.join('_')
+      end
+
+      def build_flat_dark_path
+        [
+          'DarkFlat',
+          "FLATSET_#{@metadata.flatset_id}",
+          iso_or_gain,
+          "EXP_#{@metadata.exposure}",
+          "Bin_#{@metadata.bin}",
+          "CAMERA_#{@metadata.camera || '????'}",
+        ].compact.join('_')
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/path_builders/flat_path_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module PathBuilders
+    # Builds folder paths for flat field frames.
+    #
+    # Flat frames are organized by the following keywords, which allow WBPP to
+    # automatically match flats to lights during the flat field calibration step:
+    #
+    #   Flat_FLATSET_<date>_ISO_<value>_EXP_<value>_Bin_<value>_TELESCOPE_<name>_FILTER_<name>_CAMERA_<model>
+    #
+    # **Keyword meanings:**
+    # - FLATSET: Date-based grouping (typically the morning after lights were captured)
+    # - ROTATION: Normalized rotation angle (module 180 to ignore meridian flip, only present if rotation is in FITS)
+    # - ISO: Camera ISO setting (if ISO is recorded, mutually exclusive with GAIN)
+    # - GAIN: Camera gain setting (if gain is recorded, mutually exclusive with ISO)
+    # - EXP: Exposure time (note: WBPP requires matching EXP on flats to lights in WBPP_Integration)
+    # - Bin: Binning mode
+    # - TELESCOPE: Optical equipment used (refractor, Newtonian, etc.)
+    # - FILTER: Filter used (luminance, Ha, OIII, etc.)
+    # - CAMERA: Camera model
+    #
+    # These flats are typically grouped together with their corresponding flat darks in the
+    # same FLATSET directory so WBPP can load both in one step during the WBPP_Flats process.
+    #
+    # Important: After generating master flats in WBPP, remove the "EXP_*" segment from the
+    # filename so that WBPP_Integration can automatically match them to lights. Keywords must
+    # match exactly between files for WBPP to match them.
+    #
+    # See README.md for details on WBPP_Flats process icon and keyword matching.
+    class FlatPathBuilder < BasePathBuilder
+      # @return [String] The folder path for this flat frame
+      def build
+        [
+          'Flat',
+          "FLATSET_#{@metadata.flatset_id}",
+          @metadata.normalized_rotation&.then { |r| "ROTATION_#{r}deg" },
+          iso_or_gain,
+          "EXP_#{@metadata.exposure}",
+          "Bin_#{@metadata.bin}",
+          "TELESCOPE_#{@metadata.telescope || '????'}",
+          "FILTER_#{@metadata.filter || '????'}",
+          "CAMERA_#{@metadata.camera || '????'}",
+        ].compact.join('_')
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/path_builders/light_path_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module PathBuilders
+    # rubocop:disable Layout/LineLength
+    # Builds folder paths for light (science) frames.
+    #
+    # Light frames are organized by the following keywords, which allow WBPP to
+    # automatically match lights to calibration frames (darks and flats) during integration:
+    #
+    # **Pattern:**
+    #   Light_<target>_PANE_<pane>_FLATSET_<date>_ROTATION_<angle>deg_ISO_<value>_EXP_<value>_Bin_<value>_CCD-TEMP_<value>_TELESCOPE_<name>_FILTER_<name>_CAMERA_<model>
+    #
+    # **Keyword meanings:**
+    # - Target: Object being imaged (e.g., M42, NGC1977)
+    # - PANE: Mosaic pane identifier (e.g., 1-1, 1-2) - optional
+    # - FLATSET: Date-based grouping matching the flats/darks captured for this light set
+    # - ROTATION: Normalized rotation angle (module 180 to ignore meridian flip, only present if rotation is in FITS)
+    # - ISO/GAIN: Camera ISO or GAIN setting (must match darks and flats)
+    # - EXP: Exposure time (must match darks and flats)
+    # - Bin: Binning mode (must match darks and flats)
+    # - CCD-TEMP: Rounded CCD temperature (used to group frames for calibration consistency)
+    # - TELESCOPE: Optical equipment used
+    # - FILTER: Filter used
+    # - CAMERA: Camera model
+    #
+    # The keywords are used by WBPP_Integration to automatically select matching darks,
+    # flats, and biases for each light frame during the calibration and integration process.
+    #
+    # See README.md for details on WBPP_Integration process icon and keyword matching.
+    # rubocop:enable Layout/LineLength
+    class LightPathBuilder < BasePathBuilder
+      # @return [String] The folder path for this light frame
+      def build
+        pane_segment = @metadata.mosaic_pane ? "_PANE_#{@metadata.mosaic_pane}" : ''
+        prefix = "Light_#{@metadata.target}#{pane_segment}"
+
+        [
+          prefix,
+          "FLATSET_#{@metadata.flatset_id}",
+          @metadata.normalized_rotation&.then { |r| "ROTATION_#{r}deg" },
+          iso_or_gain,
+          "EXP_#{@metadata.exposure}",
+          "Bin_#{@metadata.bin}",
+          "CCD-TEMP_#{@metadata.rounded_ccd_temp}",
+          "TELESCOPE_#{@metadata.telescope || '????'}",
+          "FILTER_#{@metadata.filter || '????'}",
+          "CAMERA_#{@metadata.camera || '????'}",
+        ].compact.join('_')
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/empty_directory_cleaner.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module Utils
+    # A cleanup utility that removes empty directories from `path` and all
+    # its subdirectories. Useful after organizing and moving subframes.
+    class EmptyDirectoryCleaner
+      include Logging
+
+      attr_reader :path
+
+      def initialize(path = Dir.pwd)
+        @path = path
+      end
+
+      # Removes empty directories under the given directory.
+      def cleanup(dry_run: false, verbose: false)
+        logger.info 'Cleaning up empty directories...'
+
+        Dir.glob('**//*/', base: path).reverse_each do |dir|
+          full_path = File.join(path, dir)
+          entries   = Dir.entries(full_path) - ['.', '..', '.DS_Store']
+
+          next unless entries.empty?
+
+          unless dry_run
+            ds_store = File.join(full_path, '.DS_Store')
+            FileUtils.rm_f(ds_store, verbose: verbose)
+            FileUtils.rmdir(full_path, verbose: verbose)
+          end
+          logger.debug "rmdir #{full_path}"
+        end
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/exif_renamer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'exiftool_vendored'
+
+module AstroSubframeOrganizer
+  module Utils
+    # Renames CR2 files based on EXIF data to match the standard subframe naming
+    # convention: TYPE_TARGET_EXPTIME_BIN_CAMERA_ISO_DATETIME_TEMP_SEQ.CR2
+    class ExifRenamer
+      include Logging
+      include ExposureFormat
+
+      RAW_NAME_PATTERN = /^(IMG_|DSC_|_DSC|DSCN)/
+
+      EXIF_DT_FORMAT = '%Y:%m:%d %H:%M:%S%z'
+
+      attr_reader :path
+
+      def initialize(path = Dir.pwd)
+        @path = path
+      end
+
+      def rename(type:, target: nil, dry_run: false)
+        Exiftool.command = 'exiftool.exe' if Gem.win_platform?
+
+        cr2_files = find_cr2_files
+
+        if cr2_files.empty?
+          logger.warn 'No CR2 files found.'
+          return
+        end
+
+        e = Exiftool.new(cr2_files)
+        bar = TTY::ProgressBar.new(
+          'Renameing files from EXIF data [:bar] :current/:total (:percent) :eta',
+          total: e.files_with_results.size,
+        )
+
+        e.files_with_results.each do |cr2|
+          exif = e.result_for(cr2)
+          rename_file(cr2, exif, type: type, target: target, dry_run: dry_run, bar: bar)
+        end
+      end
+
+      def already_named?(files)
+        files.none? { |file| File.basename(file).match?(RAW_NAME_PATTERN) }
+      end
+
+      def find_cr2_files
+        exts = Config.raw_extensions.flat_map { |ext| [ext.downcase, ext.upcase] }
+        Dir.glob(exts.map { |e| "**/*#{e}" }, base: path)
+           .map { |f| File.expand_path(File.join(path, f)) }
+           .uniq
+      end
+
+      def revert(dry_run: false)
+        cr2_files = find_cr2_files # recursive search
+
+        if cr2_files.empty?
+          logger.warn 'No CR2 files found.'
+          return
+        end
+
+        cr2_files.each_with_index do |file, index|
+          idx         = derive_sequence_number_from_filename(file) || (index + 1)
+          filename    = "IMG_#{idx.to_s.rjust(4, '0')}.CR2"
+          target_file = File.join(File.dirname(file), filename)
+
+          logger.info "Renaming #{File.basename(file)} to #{filename}"
+          FileUtils.move(file, target_file, verbose: dry_run, noop: dry_run) unless File.exist?(target_file)
+        end
+      end
+
+      private
+
+      def rename_file(cr2, exif, type:, target:, dry_run:, bar: nil)
+        filename = build_filename(exif, type: type, target: target)
+        target_file = File.join(File.dirname(cr2), filename)
+
+        if File.exist?(target_file)
+          msg = "Skipping #{cr2}, target #{target_file} already exists."
+          bar ? bar.log(msg) : logger.warn(msg)
+          return
+        end
+
+        FileUtils.mv(cr2, target_file, verbose: dry_run, noop: dry_run)
+      end
+
+      def get_exif_value(exif, mapping_key)
+        tags = Config.exif_tag_mappings[mapping_key] || []
+        tags.each do |tag|
+          return exif[tag] if exif[tag]
+        end
+        nil
+      end
+
+      def derive_sequence_number_from_filename(path)
+        File.basename(path, '.*').split(/[_-]/).last.to_i
+      end
+
+      def build_filename(exif, type:, target:)
+        exp_str    = format_exposure(get_exif_value(exif, 'exposure'))
+        created_at = resolve_time(exif).strftime(FILENAME_DT_FORMAT)
+        ccd_temp   = format('%.1fC', get_exif_value(exif, 'temperature').to_f)
+        seq_num    = derive_sequence_number_from_filename(exif.source_file).to_s.rjust(4, '0')
+        camera     = resolve_camera(get_exif_value(exif, 'model'))
+
+        [type, target, exp_str, 'Bin1', camera, "ISO#{get_exif_value(exif, 'iso')}", created_at, ccd_temp, seq_num] # rubocop:disable Style/StringConcatenation
+          .compact
+          .join('_') + '.CR2'
+      end
+
+      def resolve_camera(cam_model)
+        camera = Equipment::Camera.all.find { |c| cam_model.include?(c) }
+        if camera.nil?
+          logger.warn "Camera #{cam_model} did not match any expected models."
+          cam_model
+        else
+          camera
+        end
+      end
+
+      def resolve_time(exif)
+        dt = get_exif_value(exif, 'timestamp')
+        tz = exif[:time_zone] || '+00:00'
+        Time.strptime("#{dt}#{tz}", EXIF_DT_FORMAT)
+      rescue ArgumentError
+        Time.parse(dt)
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/exposure_format.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module Utils
+    # Utility module to format exposure times in a human-readable way for path building and filename generation.
+    module ExposureFormat
+      # Formats an exposure time in seconds into a string with appropriate units (s, ms, or us).
+      # @param exp_time [Numeric] The exposure time in seconds
+      # @return [String] The formatted exposure time with units (e.g., "30.0s", "500.0ms", "250.0us")
+      def format_exposure(exp_time)
+        exp_time  = exp_time.to_f
+        unit      = 's'
+        if exp_time < 1.0
+          exp_time *= 1000
+          unit = 'ms'
+        end
+        if exp_time < 1.0
+          exp_time *= 1000
+          unit = 'us'
+        end
+        format('%<time>.1f%<unit>s', time: exp_time, unit: unit)
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/file_utils.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module FileUtils # rubocop:disable Style/Documentation
+  # We redefine the internal output method used by FileUtils
+  def self.fu_output_message(msg)
+    AstroSubframeOrganizer.logger.info(msg)
+  end
+end

data/lib/astro_subframe_organizer/utils/fits_stripper.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module Utils
+    # Strips image data and identifying location information from FITS files.
+    # The resulting file is valid FITS with NAXIS set to 0, meaning no
+    # data array follows the header block.
+    #
+    # Location headers stripped: SITELAT, SITELONG, SITEELEV, RA, DEC,
+    # OBJCTRA, OBJCTDEC, CRVAL1, CRVAL2, CRPIX1, CRPIX2, and WCS keywords.
+    class FitsStripper
+      BLOCK_SIZE      = 2880
+      CARD_SIZE       = 80
+      CARDS_PER_BLOCK = BLOCK_SIZE / CARD_SIZE
+
+      LOCATION_HEADERS = %w[
+        SITELAT
+        SITELONG
+        SITEELEV
+        RA
+        DEC
+        OBJCTRA
+        OBJCTDEC
+      ].freeze
+
+      # WCS (World Coordinate System) headers that encode pointing information
+      WCS_PREFIXES = %w[CRVAL CRPIX CD1_ CD2_ A_ B_ AP_ BP_ CTYPE CUNIT].freeze
+
+      def self.strip(input_path, output_path = nil)
+        new(input_path, output_path).strip
+      end
+
+      def initialize(input_path, output_path = nil)
+        @input_path  = input_path
+        @output_path = output_path || input_path # default to in-place
+      end
+
+      def already_stripped?
+        File.open(@input_path, 'rb') do |f|
+          loop do
+            block = f.read(BLOCK_SIZE)
+            return false unless block&.length == BLOCK_SIZE
+
+            cards = block.scan(/.{#{CARD_SIZE}}/mo)
+            naxis_card = cards.find { |c| c.start_with?('NAXIS   =') }
+            return naxis_card.match?(/=\s+0\b/) if naxis_card
+
+            return false if header_end?(block)
+          end
+        end
+        false
+      end
+
+      def strip
+        header_blocks = read_header_blocks
+        patched       = patch_naxis(header_blocks)
+        patched       = strip_location_headers(patched)
+        File.binwrite(@output_path, patched)
+        @output_path
+      end
+
+      private
+
+      def read_header_blocks
+        blocks = []
+        File.open(@input_path, 'rb') do |f|
+          loop do
+            block = f.read(BLOCK_SIZE)
+            break unless block&.length == BLOCK_SIZE
+
+            blocks << block
+            break if header_end?(block)
+          end
+        end
+        blocks.join
+      end
+
+      def patch_naxis(header_data)
+        header_data.gsub(/NAXIS   =\s+\d+/) { |m| 'NAXIS   =                    0'.ljust(m.length) }
+      end
+
+      def strip_location_headers(header_data)
+        cards = header_data.scan(/.{#{CARD_SIZE}}/mo)
+        cards.map do |card|
+          if location_header?(card)
+            blank_card
+          else
+            card
+          end
+        end.join
+      end
+
+      def location_header?(card)
+        key = card[0, 8].strip
+        LOCATION_HEADERS.include?(key) ||
+          WCS_PREFIXES.any? { |prefix| key.start_with?(prefix) }
+      end
+
+      def blank_card
+        ' ' * CARD_SIZE
+      end
+
+      def header_end?(block)
+        block.scan(/.{#{CARD_SIZE}}/mo).any? { |card| card.start_with?('END ') }
+      end
+
+      def stripped_path(input_path)
+        dir      = File.dirname(input_path)
+        basename = File.basename(input_path, '.*')
+        ext      = File.extname(input_path)
+        File.join(dir, "#{basename}_stripped#{ext}")
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/raw_stripper.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'exiftool_vendored'
+
+module AstroSubframeOrganizer
+  module Utils
+    # Strips RAW files down to their metadata by creating a MIE (Metadata Information Extraction) file using exiftool.
+    # This is useful for users who want to keep metadata but remove large image data from their RAW files, for example
+    # to generate test fixtures where metadata is important, but image data is not needed.
+    class RawStripper
+      def initialize(input_path, output_path)
+        @input = input_path
+        @output = output_path
+      end
+
+      def already_stripped?
+        # A stripped RAW (MIE file) is typically under 1MB,
+        # whereas a real RAW is 20MB+.
+        return false unless File.exist?(@output)
+
+        File.size(@output) < 1_048_576
+      end
+
+      def strip # rubocop:disable Naming/PredicateMethod
+        # We use exiftool to create a Metadata Information Extraction (MIE) file.
+        # This contains all metadata but zero image data.
+        # We then save it with the original extension so the parsers recognize it.
+        tmp_mie = "#{@output}.mie"
+        Exiftool.command = 'exiftool.exe' if Gem.win_platform?
+
+        # -o specifies the output file. exiftool creates a MIE file if the extension is .mie
+        # -all:all ensures we copy all metadata blocks (EXIF, MakerNotes, etc.)
+        success = system("#{Exiftool.command} -o \"#{tmp_mie}\" -all:all \"#{@input}\" > /dev/null 2>&1")
+
+        if success && File.exist?(tmp_mie)
+          FileUtils.mkdir_p(File.dirname(@output))
+          FileUtils.mv(tmp_mie, @output, force: true)
+          true
+        else
+          FileUtils.rm_f(tmp_mie)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/thumbnail_cleaner.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module Utils
+    # A cleanup utility that removes thumbnail images with filenames mattching `pattern`
+    # from `path` and all its subdirectories.
+    class ThumbnailCleaner
+      include Logging
+
+      ASIAIR_THUMBNAIL_PATTERN = '**/**_thn.jpg'
+
+      attr_reader :path
+
+      def initialize(path = Dir.pwd)
+        @path = path
+      end
+
+      # Removes all the jpg thumbnails under the given directory.
+      def cleanup(pattern: ASIAIR_THUMBNAIL_PATTERN, dry_run: false, verbose: false)
+        logger.info 'Removing jpg thumbnails...'
+        Dir.glob([pattern], base: path)
+           .each { |thumbnail| FileUtils.rm File.join(path, thumbnail), noop: dry_run, verbose: verbose }
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/utils/unorganizer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  module Utils
+    # Moves all FITS and CR2 files from subdirectories back into the target directory.
+    # Useful for undoing an organize run so files can be re-organized with different settings.
+    class Unorganizer
+      include Logging
+
+      attr_reader :path
+
+      def initialize(path = Dir.pwd)
+        @path = path
+      end
+
+      def unorganize(dry_run: false, verbose: false)
+        files = find_organized_files
+
+        if files.empty?
+          logger.info 'No organized files found.'
+          return
+        end
+
+        logger.info "Preparing to move #{files.size} files to #{path}..."
+
+        bar = TTY::ProgressBar.new('Moving files [:bar] :current/:total (:percent) :eta', total: files.size)
+
+        files.each do |file|
+          dest = File.join(path, File.basename(file))
+          if File.exist?(dest)
+            bar.log "Skipping #{File.basename(file)}, already exists in #{path}."
+            next
+          end
+          FileUtils.mv(file, dest, verbose: verbose || dry_run, noop: dry_run)
+          bar.advance(1)
+        end
+
+        cleanup_empty_dirs(dry_run: dry_run) unless dry_run
+      end
+
+      private
+
+      def find_organized_files
+        Dir.glob(['**/*.fit', '**/*.FIT', '**/*.cr2', '**/*.CR2'], base: path)
+           .map { |f| File.join(path, f) }
+           .reject { |f| File.dirname(f) == path }
+      end
+
+      def cleanup_empty_dirs(dry_run: false, verbose: false)
+        EmptyDirectoryCleaner.new(path).cleanup(dry_run: dry_run, verbose: verbose)
+      end
+    end
+  end
+end

data/lib/astro_subframe_organizer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AstroSubframeOrganizer
+  VERSION = '0.0.2'
+end