exrviewer 0.1.0.beta1

data/lib/exr_viewer/active_storage/exr_previewer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "set"
+require "tempfile"
+require "active_storage/previewer"
+require "active_storage/errors"
+require "image_processing/vips"
+require "vips"
+
+module ExrViewer
+  module ActiveStorage
+    class ExrPreviewer < ::ActiveStorage::Previewer
+      EXR_CONTENT_TYPES = Set.new([
+        "image/x-exr",
+        "image/exr",
+        "application/x-exr",
+        "application/exr"
+      ]).freeze
+
+      FALLBACK_CONTENT_TYPES = Set.new([
+        "application/octet-stream",
+        "binary/octet-stream"
+      ]).freeze
+
+      MAX_EDGE = 1600
+      JPEG_QUALITY = 85
+      GAMMA_EXPONENT = 1.0 / 2.2
+
+      class << self
+        def accept?(blob)
+          content_type = blob.content_type.to_s.downcase
+          return true if EXR_CONTENT_TYPES.include?(content_type)
+
+          extension = blob.filename.extension_without_delimiter.to_s.downcase
+          FALLBACK_CONTENT_TYPES.include?(content_type) && extension == "exr"
+        end
+      end
+
+      def preview(**options)
+        download_blob_to_tempfile do |input|
+          output = Tempfile.new([blob.filename.base.to_s, ".jpg"], binmode: true)
+
+          begin
+            render_preview(input.path, output.path)
+
+            File.open(output.path, "rb") do |io|
+              yield io: io,
+                    filename: "#{blob.filename.base}.jpg",
+                    content_type: "image/jpeg",
+                    **options
+            end
+          ensure
+            output.close!
+          end
+        end
+      rescue LoadError => e
+        raise ::ActiveStorage::UnpreviewableError,
+              "EXR previewing requires image_processing and ruby-vips (#{e.message})"
+      rescue StandardError => e
+        raise e if e.is_a?(::ActiveStorage::UnpreviewableError)
+
+        raise ::ActiveStorage::UnpreviewableError,
+              "Unable to generate EXR preview: #{e.message}"
+      end
+
+      private
+
+      def render_preview(input_path, output_path)
+        input = ::Vips::Image.new_from_file(input_path, access: :sequential)
+        rgb = best_effort_rgb(input)
+        rgb = rgb.cast("float")
+        rgb = rgb.clamp(min: 0.0, max: 1.0)
+        rgb = rgb.pow(GAMMA_EXPONENT)
+
+        linear_png = Tempfile.new(["exr-linear", ".png"], binmode: true)
+        begin
+          rgb.pngsave(linear_png.path, compression: 3)
+
+          ImageProcessing::Vips
+            .source(linear_png.path)
+            .resize_to_limit(MAX_EDGE, MAX_EDGE)
+            .convert("jpg")
+            .saver(Q: JPEG_QUALITY, strip: true)
+            .call(destination: output_path)
+        ensure
+          linear_png.close!
+        end
+      end
+
+      def best_effort_rgb(image)
+        if image.bands >= 3
+          image.extract_band(0, n: 3)
+        elsif image.bands == 2
+          image.bandjoin(image.extract_band(0, n: 1))
+        else
+          image.bandjoin([image, image])
+        end
+      end
+    end
+  end
+end

data/lib/exr_viewer/helpers.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "set"
+
+module ExrViewer
+  module Helpers
+    COMPONENT_ATTRIBUTES = Set.new([
+      "tone-mapping",
+      "exposure",
+      "controls"
+    ]).freeze
+
+    HTML_ATTRIBUTES = Set.new([
+      "id",
+      "class",
+      "style",
+      "title",
+      "role",
+      "hidden",
+      "tabindex",
+      "lang",
+      "dir",
+      "slot",
+      "part"
+    ]).freeze
+
+    ATTRIBUTE_ALIASES = {
+      "tone_mapping" => "tone-mapping"
+    }.freeze
+
+    def exr_viewer_include_tag(optional: true, **attrs)
+      return "".html_safe if optional && exr_viewer_managed_by_js_pipeline?
+
+      defaults = { defer: true }
+      javascript_include_tag("exr-viewer-stimulus", **defaults.merge(attrs))
+    end
+
+    def exr_viewer_tag(src:, **attrs)
+      normalized = normalize_component_attrs(attrs)
+      component = extract_component_attributes(normalized)
+      data_attributes = extract_data_attributes(normalized)
+      merge_controller_identifier(data_attributes, "exr-viewer")
+
+      data_attributes["exr-viewer-src-value"] = resolve_exr_src(src)
+      data_attributes["exr-viewer-tone-mapping-value"] = component.fetch("tone-mapping", "aces")
+      data_attributes["exr-viewer-exposure-value"] = component.fetch("exposure", 1.0)
+      data_attributes["exr-viewer-controls-value"] = component.fetch("controls", false) ? true : false
+
+      normalized["data"] = data_attributes
+      merge_class_name(normalized, "exr-viewer")
+
+      content_tag("div", "", normalized)
+    end
+
+    def exr_preview_tag(source, preview: {}, **attrs)
+      image_tag(resolve_exr_preview_source(source, preview_options: preview), **attrs)
+    end
+
+    private
+
+    def resolve_exr_src(source)
+      return source if source.is_a?(String)
+
+      if active_storage_blob?(source) || active_storage_attachment?(source)
+        return url_for(source)
+      end
+
+      raise ArgumentError, "src must be a String, ActiveStorage::Blob, or ActiveStorage::Attachment"
+    end
+
+    def active_storage_blob?(source)
+      defined?(::ActiveStorage::Blob) && source.is_a?(::ActiveStorage::Blob)
+    end
+
+    def active_storage_attachment?(source)
+      defined?(::ActiveStorage::Attachment) && source.is_a?(::ActiveStorage::Attachment)
+    end
+
+    def resolve_exr_preview_source(source, preview_options:)
+      return source if source.is_a?(String)
+
+      if active_storage_blob?(source) || active_storage_attachment?(source)
+        return source.preview(**preview_options).processed
+      end
+
+      raise ArgumentError, "source must be a String, ActiveStorage::Blob, or ActiveStorage::Attachment"
+    end
+
+    def exr_viewer_managed_by_js_pipeline?
+      exr_viewer_importmap_setup? || exr_viewer_node_setup?
+    end
+
+    def exr_viewer_importmap_setup?
+      exr_viewer_app_file_exists?("config/importmap.rb")
+    end
+
+    def exr_viewer_node_setup?
+      exr_viewer_app_file_exists?("package.json")
+    end
+
+    def exr_viewer_app_file_exists?(relative_path)
+      return false unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      File.exist?(Rails.root.join(relative_path))
+    end
+
+    def extract_component_attributes(normalized)
+      component = {}
+      COMPONENT_ATTRIBUTES.each do |key|
+        next unless normalized.key?(key)
+
+        component[key] = normalized.delete(key)
+      end
+      component
+    end
+
+    def extract_data_attributes(normalized)
+      data_attributes = {}
+
+      data = normalized.delete("data")
+      if data.is_a?(Hash)
+        data.each do |key, value|
+          data_attributes[key.to_s.tr("_", "-")] = value
+        end
+      end
+
+      normalized.keys.grep(/\Adata-/).each do |key|
+        data_attributes[key.delete_prefix("data-")] = normalized.delete(key)
+      end
+
+      data_attributes
+    end
+
+    def merge_controller_identifier(data_attributes, identifier)
+      current = data_attributes.fetch("controller", "").to_s.split(/\s+/).reject(&:empty?)
+      current << identifier unless current.include?(identifier)
+      data_attributes["controller"] = current.join(" ")
+    end
+
+    def merge_class_name(normalized, css_class)
+      classes = normalized.fetch("class", "").to_s.split(/\s+/).reject(&:empty?)
+      classes << css_class unless classes.include?(css_class)
+      normalized["class"] = classes.join(" ")
+    end
+
+    def normalize_component_attrs(attrs)
+      normalized = {}
+
+      attrs.each do |raw_key, value|
+        key = canonical_attr_name(raw_key)
+
+        unless allowed_attr?(key)
+          raise ArgumentError, "Unknown exr_viewer_tag attribute: #{raw_key}"
+        end
+
+        normalized[key] = value
+      end
+
+      normalized
+    end
+
+    def canonical_attr_name(raw_key)
+      string_key = raw_key.to_s
+      ATTRIBUTE_ALIASES.fetch(string_key, string_key.tr("_", "-"))
+    end
+
+    def allowed_attr?(key)
+      COMPONENT_ATTRIBUTES.include?(key) ||
+        HTML_ATTRIBUTES.include?(key) ||
+        key.start_with?("data-") ||
+        key.start_with?("aria-") ||
+        key == "data" ||
+        key == "aria"
+    end
+  end
+end

data/lib/exr_viewer/railtie.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module"
+
+module ExrViewer
+  class Engine < ::Rails::Engine
+    initializer "exr_viewer.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include ExrViewer::Helpers
+      end
+    end
+
+    initializer "exr_viewer.assets.precompile" do |app|
+      next unless app.config.respond_to?(:assets)
+      next unless app.config.assets.respond_to?(:precompile)
+
+      app.config.assets.precompile << "exr-viewer-stimulus.js"
+    end
+
+    initializer "exr_viewer.active_storage.previewer" do
+      config.after_initialize do
+        next unless defined?(::ActiveStorage)
+        next unless ::ActiveStorage.respond_to?(:previewers)
+
+        previewer = ExrViewer::ActiveStorage::ExrPreviewer
+        unless ::ActiveStorage.previewers.include?(previewer)
+          ::ActiveStorage.previewers << previewer
+        end
+      end
+    end
+  end
+end

data/lib/exr_viewer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ExrViewer
+  VERSION = "0.1.0.beta1"
+end

data/lib/exr_viewer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "exr_viewer/version"
+require "exr_viewer/helpers"
+require "exr_viewer/active_storage/exr_previewer"
+require "exr_viewer/railtie" if defined?(Rails::Railtie)
+
+module ExrViewer
+end

data/lib/generators/exr_viewer/install/install_generator.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "json"
+require "rails/generators"
+
+module ExrViewer
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :strategy,
+                   type: :string,
+                   default: "auto",
+                   desc: "Install strategy: auto, bun, node, importmap, vendored"
+      class_option :skip_install,
+                   type: :boolean,
+                   default: false,
+                   desc: "Skip package manager install commands"
+
+      THREE_VERSION = "0.164.1"
+      THREE_PACKAGE = "three"
+      STIMULUS_PACKAGE = "@hotwired/stimulus"
+
+      IMPORTMAP_STIMULUS_PIN = %(pin "@hotwired/stimulus", to: "stimulus.min.js")
+      IMPORTMAP_STIMULUS_LOADING_PIN = %(pin "@hotwired/stimulus-loading", to: "stimulus-loading.js")
+      IMPORTMAP_CONTROLLERS_PIN = %(pin_all_from "app/javascript/controllers", under: "controllers")
+      IMPORTMAP_THREE_PIN = %(pin "three", to: "https://ga.jspm.io/npm:three@#{THREE_VERSION}/build/three.module.js")
+      IMPORTMAP_EXR_LOADER_PIN = %(pin "three/examples/jsm/loaders/EXRLoader.js", to: "https://ga.jspm.io/npm:three@#{THREE_VERSION}/examples/jsm/loaders/EXRLoader.js")
+      IMPORTMAP_WEBGPU_RENDERER_PIN = %(pin "three/examples/jsm/renderers/webgpu/WebGPURenderer.js", to: "https://ga.jspm.io/npm:three@#{THREE_VERSION}/examples/jsm/renderers/webgpu/WebGPURenderer.js")
+
+      def install
+        strategy = resolve_strategy
+        say_status :exr_viewer, "Using #{strategy} install strategy", :blue
+
+        case strategy
+        when "bun"
+          install_bun
+        when "node"
+          install_node
+        when "importmap"
+          install_importmap
+        when "vendored"
+          install_vendored
+        else
+          raise Thor::Error, "Unsupported strategy: #{strategy}"
+        end
+      end
+
+      private
+
+      def resolve_strategy
+        selected = options[:strategy].to_s
+        selected = "auto" if selected.empty?
+
+        return detect_strategy if selected == "auto"
+
+        valid = %w[bun node importmap vendored]
+        unless valid.include?(selected)
+          raise Thor::Error, "Unknown --strategy=#{selected}. Use one of: auto, #{valid.join(', ')}"
+        end
+
+        selected
+      end
+
+      def detect_strategy
+        return "importmap" if File.exist?(app_path("config/importmap.rb"))
+        return "bun" if bun_project?
+        return "node" if File.exist?(app_path("package.json"))
+
+        "vendored"
+      end
+
+      def bun_project?
+        File.exist?(app_path("bun.lockb")) || File.exist?(app_path("bun.lock")) || File.exist?(app_path("bunfig.toml"))
+      end
+
+      def install_bun
+        ensure_package_json!
+
+        if options[:skip_install]
+          add_package_dependencies([THREE_PACKAGE, STIMULUS_PACKAGE])
+        else
+          run "bun add #{THREE_PACKAGE} #{STIMULUS_PACKAGE}"
+        end
+
+        ensure_node_stimulus_setup
+        copy_controller_template
+      end
+
+      def install_node
+        ensure_package_json!
+
+        if options[:skip_install]
+          add_package_dependencies([THREE_PACKAGE, STIMULUS_PACKAGE])
+        else
+          run "#{node_add_command} #{THREE_PACKAGE} #{STIMULUS_PACKAGE}"
+        end
+
+        ensure_node_stimulus_setup
+        copy_controller_template
+      end
+
+      def install_importmap
+        importmap_path = app_path("config/importmap.rb")
+        raise Thor::Error, "Missing config/importmap.rb for importmap strategy" unless File.exist?(importmap_path)
+
+        ensure_importmap_stimulus_setup(importmap_path)
+        copy_controller_template
+      end
+
+      def install_vendored
+        ensure_layout_include_tag
+      end
+
+      def ensure_package_json!
+        return if File.exist?(app_path("package.json"))
+
+        raise Thor::Error,
+              "Missing package.json. Run with --strategy=importmap or --strategy=vendored, or initialize JavaScript tooling first."
+      end
+
+      def add_package_dependencies(packages)
+        package_json_path = app_path("package.json")
+        package_json = JSON.parse(File.read(package_json_path))
+        package_json["dependencies"] ||= {}
+
+        packages.each do |package_name|
+          next if package_json["dependencies"].key?(package_name)
+
+          package_json["dependencies"][package_name] = package_name == THREE_PACKAGE ? "^#{THREE_VERSION}" : "^3.2.2"
+        end
+
+        File.write(package_json_path, "#{JSON.pretty_generate(package_json)}\n")
+      end
+
+      def node_add_command
+        return "yarn add" if File.exist?(app_path("yarn.lock"))
+        return "pnpm add" if File.exist?(app_path("pnpm-lock.yaml"))
+
+        "npm install"
+      end
+
+      def ensure_node_stimulus_setup
+        ensure_controllers_directory
+        ensure_controllers_application
+        ensure_node_controllers_index
+        ensure_application_import(%(import "./controllers";))
+      end
+
+      def ensure_importmap_stimulus_setup(importmap_path)
+        ensure_controllers_directory
+        ensure_controllers_application
+        ensure_importmap_controllers_index
+        ensure_application_import(%(import "controllers";))
+
+        append_line_unless_present(importmap_path, IMPORTMAP_STIMULUS_PIN)
+        append_line_unless_present(importmap_path, IMPORTMAP_STIMULUS_LOADING_PIN)
+        append_line_unless_present(importmap_path, IMPORTMAP_CONTROLLERS_PIN)
+        append_line_unless_present(importmap_path, IMPORTMAP_THREE_PIN)
+        append_line_unless_present(importmap_path, IMPORTMAP_EXR_LOADER_PIN)
+        append_line_unless_present(importmap_path, IMPORTMAP_WEBGPU_RENDERER_PIN)
+      end
+
+      def ensure_controllers_directory
+        empty_directory app_path("app/javascript/controllers")
+      end
+
+      def ensure_controllers_application
+        application_path = app_path("app/javascript/controllers/application.js")
+        return if File.exist?(application_path)
+
+        copy_file "controllers_application.js", application_path
+      end
+
+      def ensure_node_controllers_index
+        index_path = app_path("app/javascript/controllers/index.js")
+        unless File.exist?(index_path)
+          copy_file "controllers_index_for_node.js", index_path
+        end
+
+        unless File.read(index_path).include?("import { application }")
+          append_line_unless_present(index_path, %(import { application } from "./application"))
+        end
+        append_line_unless_present(index_path, %(import ExrViewerController from "./exr_viewer_controller"))
+        append_line_unless_present(index_path, %(application.register("exr-viewer", ExrViewerController)))
+      end
+
+      def ensure_importmap_controllers_index
+        index_path = app_path("app/javascript/controllers/index.js")
+        return if File.exist?(index_path)
+
+        copy_file "controllers_index_for_importmap.js", index_path
+      end
+
+      def copy_controller_template
+        controller_path = app_path("app/javascript/controllers/exr_viewer_controller.js")
+        return if File.exist?(controller_path)
+
+        copy_file "exr_viewer_controller.js", controller_path
+      end
+
+      def ensure_application_import(import_line)
+        application_js_path = app_path("app/javascript/application.js")
+        unless File.exist?(application_js_path)
+          empty_directory app_path("app/javascript")
+          File.write(application_js_path, "")
+        end
+
+        append_line_unless_present(application_js_path, import_line)
+      end
+
+      def ensure_layout_include_tag
+        layout_path = app_path("app/views/layouts/application.html.erb")
+        unless File.exist?(layout_path)
+          say_status :warn, "No app/views/layouts/application.html.erb found. Add <%= exr_viewer_include_tag %> to your layout.", :yellow
+          return
+        end
+
+        layout = File.read(layout_path)
+        return if layout.include?("<%= exr_viewer_include_tag")
+
+        if layout.include?("</head>")
+          updated = layout.sub("</head>", "  <%= exr_viewer_include_tag %>\n</head>")
+          File.write(layout_path, updated)
+        else
+          File.write(layout_path, "#{layout}\n<%= exr_viewer_include_tag %>\n")
+        end
+      end
+
+      def append_line_unless_present(path, line)
+        contents = File.read(path)
+        return if contents.include?(line)
+
+        separator = contents.end_with?("\n") || contents.empty? ? "" : "\n"
+        File.write(path, "#{contents}#{separator}#{line}\n")
+      end
+
+      def app_path(relative_path)
+        File.expand_path(relative_path, destination_root)
+      end
+    end
+  end
+end

data/lib/generators/exr_viewer/install/templates/controllers_application.js

@@ -0,0 +1,7 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+application.debug = false
+window.Stimulus = application
+
+export { application }

data/lib/generators/exr_viewer/install/templates/controllers_index_for_importmap.js

@@ -0,0 +1,4 @@
+import { application } from "controllers/application"
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+
+eagerLoadControllersFrom("controllers", application)

data/lib/generators/exr_viewer/install/templates/controllers_index_for_node.js

@@ -0,0 +1 @@
+import { application } from "./application"