stac 0.1.0 → 0.3.0

data/Rakefile

@@ -1,19 +1,77 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'rdoc/task'
+
 RSpec::Core::RakeTask.new(:spec)
 
-require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
 
-require 'rdoc/task'
 RDoc::Task.new do |rdoc|
   rdoc.rdoc_dir = 'doc'
   rdoc.title = 'stac-ruby API docs'
-  rdoc.rdoc_files.include('README.md', 'CHANGELOG.md', 'lib/**/*.rb')
+  rdoc.rdoc_files.include('README.md', 'CHANGELOG.md', 'GETTING_STARTED.md', 'lib/**/*.rb')
   rdoc.main = 'README.md'
 end
+
+namespace :fixture do
+  desc 'Setup spec/fixtures'
+  task setup: %w[
+    spec/fixtures/stac-spec
+    spec/fixtures/eo/item.json
+    spec/fixtures/projection/item.json
+    spec/fixtures/scientific/item.json
+    spec/fixtures/scientific/collection.json
+    spec/fixtures/scientific/collection-assets.json
+    spec/fixtures/view/item.json
+  ]
+
+  desc 'Remove spec/fixtures'
+  task :clean do
+    rm_r 'spec/fixtures'
+  end
+
+  directory 'spec/fixtures/stac-spec'
+
+  file 'spec/fixtures/stac-spec' do |t|
+    cp_r 'stac-spec/examples/.', t.name
+  end
+
+  directory 'spec/fixtures/eo'
+
+  file 'spec/fixtures/eo/item.json' => 'spec/fixtures/eo' do |t|
+    sh "curl https://raw.githubusercontent.com/stac-extensions/eo/v1.0.0/examples/item.json -o #{t.name} -sS"
+  end
+
+  directory 'spec/fixtures/projection'
+
+  file 'spec/fixtures/projection/item.json' => 'spec/fixtures/projection' do |t|
+    sh "curl https://raw.githubusercontent.com/stac-extensions/projection/v1.0.0/examples/item.json -o #{t.name} -sS"
+  end
+
+  directory 'spec/fixtures/scientific'
+
+  file 'spec/fixtures/scientific/item.json' => 'spec/fixtures/scientific' do |t|
+    sh "curl https://raw.githubusercontent.com/stac-extensions/scientific/v1.0.0/examples/item.json -o #{t.name} -sS"
+  end
+
+  file 'spec/fixtures/scientific/collection.json' => 'spec/fixtures/scientific' do |t|
+    sh 'curl https://raw.githubusercontent.com/stac-extensions/scientific/v1.0.0/examples/collection.json ' \
+       "-o #{t.name} -sS"
+  end
+
+  file 'spec/fixtures/scientific/collection-assets.json' => 'spec/fixtures/scientific' do |t|
+    sh 'curl https://raw.githubusercontent.com/stac-extensions/scientific/v1.0.0/examples/collection-assets.json ' \
+       "-o #{t.name} -sS"
+  end
+
+  directory 'spec/fixtures/view'
+
+  file 'spec/fixtures/view/item.json' => 'spec/fixtures/view' do |t|
+    sh "curl https://raw.githubusercontent.com/stac-extensions/view/v1.0.0/examples/item.json -o #{t.name} -sS"
+  end
+end

data/Steepfile

@@ -15,6 +15,8 @@ target :lib do
     hash[D::Ruby::InsufficientKeywordArguments] = :hint
     hash[D::Ruby::MethodBodyTypeMismatch] = :information
     hash[D::Ruby::MethodDefinitionMissing] = nil # To supress noisy VS Code extension message.
+    hash[D::Ruby::NoMethod] = :information
+    hash[D::Ruby::UnknownConstant] = :information
     hash[D::Ruby::UnsupportedSyntax] = :hint
   end
 end

data/lib/stac/asset.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require_relative 'common_metadata'
+require_relative 'hash_like'
+
 module STAC
   # Represents \STAC asset object, which contains a link to data associated with an Item or Collection that can be
   # downloaded or streamed.
   class Asset
+    include HashLike
+    include CommonMetadata
+
     class << self
       # Deserializes an Asset from a Hash.
       def from_hash(hash)
@@ -11,7 +17,7 @@ module STAC
       end
     end
 
-    attr_accessor :href, :title, :description, :type, :roles, :extra
+    attr_accessor :href, :title, :description, :type, :roles
 
     def initialize(href:, title: nil, description: nil, type: nil, roles: nil, **extra)
       @href = href

data/lib/stac/catalog.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'pathname'
 require_relative 'errors'
 require_relative 'stac_object'
 
@@ -8,20 +9,33 @@ module STAC
   #
   # \STAC \Catalog Specification: https://github.com/radiantearth/stac-spec/tree/master/catalog-spec
   class Catalog < STAC::STACObject
-    self.type = 'Catalog'
+    @type = 'Catalog'
 
-    attr_accessor :description, :title
+    class << self
+      def root(id:, description:, href:, links: [], title: nil, stac_extensions: [], **extra)
+        catalog = new(
+          id: id, description: description, links: links, title: title, stac_extensions: stac_extensions, **extra,
+        )
+        catalog.self_href = href
+        catalog.root = catalog
+        catalog
+      end
+    end
+
+    attr_accessor :id, :description, :title
 
-    def initialize(id:, description:, links:, title: nil, stac_extensions: nil, **extra)
-      super(id: id, links: links, stac_extensions: stac_extensions, **extra)
+    def initialize(id:, description:, links: [], title: nil, stac_extensions: [], **extra)
+      @id = id
       @description = description
       @title = title
+      super(links: links, stac_extensions: stac_extensions, **extra)
     end
 
     # Serializes self to a Hash.
     def to_h
       super.merge(
         {
+          'id' => id,
           'title' => title,
           'description' => description,
         }.compact,
@@ -30,7 +44,11 @@ module STAC
 
     # Returns catalog/collection objects from rel="child" links of this catalog.
     def children
-      links.select { |link| link.rel == 'child' }.lazy.map(&:target)
+      child_links.lazy.map(&:target)
+    end
+
+    def all_children # :nodoc:
+      children.chain(children.flat_map(&:all_children)).lazy
     end
 
     # Filters only collections from #children.
@@ -38,17 +56,24 @@ module STAC
       children.select { |child| child.type == 'Collection' }
     end
 
+    # Returns all collections from this catalog and its child catalogs/collections recursively.
+    def all_collections
+      # The last `.lazy` is not necessary with Ruby 3.1.
+      # But with Ruby 3.0, it is necessary because Enumerator::Lazy#chain returns Enumerator::Chain
+      # and RBS type check fails.
+      collections.chain(children.flat_map(&:all_collections)).lazy
+    end
+
     # Returns the child catalog/collection with the given ID if it exists.
     #
     # With option `recusive: true`, it will traverse all child catalogs/collections recursively.
     def find_child(id, recursive: false)
-      targets = recursive ? children.chain(children.flat_map(&:children)) : children
-      targets.find { |child| child.id == id }
+      (recursive ? all_children : children).find { |child| child.id == id }
     end
 
     # Returns item objects from rel="item" links of this catalog.
     def items
-      links.select { |link| link.rel == 'item' }.lazy.map(&:target)
+      item_links.lazy.map(&:target)
     end
 
     # Returns all items from this catalog and its child catalogs/collections recursively.
@@ -56,7 +81,7 @@ module STAC
       # The last `.lazy` is not necessary with Ruby 3.1.
       # But with Ruby 3.0, it is necessary because Enumerator::Lazy#chain returns Enumerator::Chain
       # and RBS type check fails.
-      items.chain(children.flat_map(&:items)).lazy
+      items.chain(children.flat_map(&:all_items)).lazy
     end
 
     # Returns the item with the given ID if it exists.
@@ -65,5 +90,52 @@ module STAC
     def find_item(id, recursive: false)
       (recursive ? all_items : items).find { |item| item.id == id }
     end
+
+    # Adds a rel="child" link to self and adds "self", "root", and "parent" links to the child catalog.
+    def add_child(catalog, href: "#{catalog.id}/#{catalog.type.downcase}.json", title: catalog.title)
+      if (base = self_href)
+        catalog.self_href = Pathname(base).dirname.join(href).to_s
+      end
+      catalog.root = root
+      catalog.parent = self
+      add_link(catalog, rel: 'child', type: 'application/json', title: title)
+    end
+
+    # Adds a rel="item" link to self and adds "self", "root", and "parent" links to the given item.
+    def add_item(item, href: "#{item.id}.json", title: item.properties.title)
+      if (base = self_href)
+        item.self_href = Pathname(base).dirname.join(href).to_s
+      end
+      item.root = root
+      item.parent = self
+      add_link(item, rel: 'item', type: 'application/geo+json', title: title)
+    end
+
+    # Exports this catalog and all its children and items to the specified dir or each self href.
+    def export(dest_dir = nil, writer: FileWriter.new)
+      dest_pathname = Pathname(dest_dir) if dest_dir
+      self_dest = dest_pathname.join(File.basename(self_href!)).to_s if dest_pathname
+      save(self_dest, writer: writer)
+
+      item_links.select(&:resolved?).each do |item_link|
+        item_dest = dest_pathname.join(item_link.relative_href!).to_s if dest_pathname
+        item_link.target.save(item_dest, writer: writer)
+      end
+
+      child_links.select(&:resolved?).each do |child_link|
+        child_dest_dir = dest_pathname.join(child_link.relative_href!).dirname.to_s if dest_pathname
+        child_link.target.export(child_dest_dir, writer: writer)
+      end
+    end
+
+    private
+
+    def child_links
+      links.select { |link| link.rel == 'child' }
+    end
+
+    def item_links
+      links.select { |link| link.rel == 'item' }
+    end
   end
 end

data/lib/stac/collection.rb

@@ -10,43 +10,46 @@ module STAC
   #
   # \STAC \Collection Specification: https://github.com/radiantearth/stac-spec/tree/master/collection-spec
   class Collection < Catalog
-    self.type = 'Collection'
+    @type = 'Collection'
 
     class << self
       def from_hash(hash)
-        h = hash.dup
-        h['extent'] = Extent.from_hash(h.fetch('extent'))
-        h['providers'] = h['providers']&.map { |provider| Provider.from_hash(provider) }
-        h['assets'] = h['assets']&.transform_values { |v| Asset.from_hash(v) }
+        h = hash.transform_keys(&:to_sym)
+        h[:extent] = Extent.from_hash(h.fetch(:extent))
+        h[:providers] = h[:providers]&.map { |provider| Provider.from_hash(provider) }
+        h[:summaries] = h[:summaries]&.transform_keys(&:to_s)
+        h[:assets] = h[:assets]&.to_h { |k, v| [k.to_s, Asset.from_hash(v)] }
         super(h)
       rescue KeyError => e
         raise ArgumentError, "required field not found: #{e.key}"
       end
     end
 
-    attr_accessor :license, :extent, :keywords, :providers, :summaries, :assets
+    attr_accessor :license, :extent, :keywords, :providers, :summaries
+
+    attr_reader :assets
 
     def initialize(
       id:,
       description:,
-      links:,
       license:,
       extent:,
+      links: [],
       title: nil,
       keywords: nil,
       providers: nil,
       summaries: nil,
       assets: nil,
-      stac_extensions: nil,
+      stac_extensions: [],
       **extra
     )
-      super(id: id, description: description, links: links, title: title, stac_extensions: stac_extensions, **extra)
       @license = license
       @extent = extent
       @keywords = keywords
       @providers = providers
       @summaries = summaries
       @assets = assets
+      super(id: id, description: description, links: links, title: title, stac_extensions: stac_extensions, **extra)
     end
 
     # Serializes self to a Hash.
@@ -62,5 +65,36 @@ module STAC
         }.compact,
       )
     end
+
+    # Adds an asset with the given key.
+    #
+    # When the item has extendable stac_extensions, make the asset extend the extension modules.
+    def add_asset(key:, href:, title: nil, description: nil, type: nil, roles: nil, **extra)
+      asset = Asset.new(href: href, title: title, description: description, type: type, roles: roles, **extra)
+      extensions.each do |extension|
+        asset.extend(extension::Asset) if extension.const_defined?(:Asset)
+      end
+      if assets
+        assets[key] = asset
+      else
+        @assets = { key => asset }
+      end
+      self
+    end
+
+    # Adds a rel="item" link to self and adds "self", "root", "parent", and "collection" links to the given item.
+    def add_item(item, href: "#{item.id}.json", title: item.properties.title)
+      super
+      item.collection = self
+      self
+    end
+
+    private
+
+    def apply_extension!(extension)
+      super
+      extend(extension::Collection) if extension.const_defined?(:Collection)
+      assets&.each_value { |asset| asset.extend(extension::Asset) } if extension.const_defined?(:Asset)
+    end
   end
 end

data/lib/stac/common_metadata.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module STAC
+  # Provides read/write methods for \STAC Common Metadata.
+  #
+  # These methods are shorthand accessors of #extra Hash.
+  # Asset and \Item Properties include this module.
+  #
+  # Specification: https://github.com/radiantearth/stac-spec/blob/master/item-spec/common-metadata.md
+  module CommonMetadata
+    attr_reader :extra
+
+    def title
+      extra['title']
+    end
+
+    def title=(str)
+      extra['title'] = str
+    end
+
+    def description
+      extra['description']
+    end
+
+    def description=(str)
+      extra['description'] = str
+    end
+
+    def created
+      if (str = extra['created'])
+        Time.iso8601(str)
+      end
+    end
+
+    def created=(time)
+      extra['created'] = case time
+                         when Time
+                           time.iso8601
+                         else
+                           time
+                         end
+    end
+
+    def updated
+      if (str = extra['updated'])
+        Time.iso8601(str)
+      end
+    end
+
+    def updated=(time)
+      extra['updated'] = case time
+                         when Time
+                           time.iso8601
+                         else
+                           time
+                         end
+    end
+
+    def start_datetime
+      if (str = extra['start_datetime'])
+        Time.iso8601(str)
+      end
+    end
+
+    def start_datetime=(time)
+      extra['start_datetime'] = case time
+                                when Time
+                                  time.iso8601
+                                else
+                                  time
+                                end
+    end
+
+    def end_datetime
+      if (str = extra['end_datetime'])
+        Time.iso8601(str)
+      end
+    end
+
+    def end_datetime=(time)
+      extra['end_datetime'] = case time
+                              when Time
+                                time.iso8601
+                              else
+                                time
+                              end
+    end
+
+    # Returns a range from #start_datetime to #end_datetime.
+    def datetime_range
+      if (start = start_datetime) && (last = end_datetime)
+        start..last
+      end
+    end
+
+    # Sets #start_datetime and #end_datetime by the given range.
+    def datetime_range=(time_range)
+      self.start_datetime = time_range.begin
+      self.end_datetime = time_range.end
+    end
+
+    def license
+      extra['license']
+    end
+
+    def license=(str)
+      extra['license'] = str
+    end
+
+    def providers
+      extra.fetch('providers', []).map do |provider_hash|
+        Provider.from_hash(provider_hash)
+      end
+    end
+
+    def providers=(arr)
+      extra['providers'] = arr.map(&:to_h)
+    end
+
+    def platform
+      extra['platform']
+    end
+
+    def platform=(str)
+      extra['platform'] = str
+    end
+
+    def instruments
+      extra['instruments']
+    end
+
+    def instruments=(arr)
+      extra['instruments'] = arr
+    end
+
+    def constellation
+      extra['constellation']
+    end
+
+    def constellation=(str)
+      extra['constellation'] = str
+    end
+
+    def mission
+      extra['mission']
+    end
+
+    def mission=(str)
+      extra['mission'] = str
+    end
+
+    def gsd
+      extra['gsd']
+    end
+
+    def gsd=(num)
+      extra['gsd'] = num
+    end
+  end
+end

data/lib/stac/errors.rb

@@ -7,9 +7,6 @@ module STAC
   # Raised when unexpected "type" field was given.
   class TypeError < Error; end
 
-  # Raised when URL with unsupported scheme was given.
-  class UnknownURISchemeError < Error; end
-
-  # Raised when a HTTP request failed.
-  class HTTPError < Error; end
+  # Raised when URL with not supported scheme was given.
+  class NotSupportedURISchemeError < Error; end
 end

data/lib/stac/extension.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module STAC
+  # Raised when an extension module does have identifier.
+  class ExtensionWithoutIdentifierError < Error; end
+
+  # \Extension modules must extend this module.
+  module Extension
+    # Returns extension id for `stac_extensions` field.
+    #
+    # When given an argument, sets the given value as its identifier.
+    def identifier(identifier = nil)
+      # @type self: Module
+      if identifier.nil?
+        @identifier or raise ExtensionWithoutIdentifierError, "extension module must be set identifier: #{name}"
+      else
+        @identifier = identifier
+      end
+    end
+
+    # Returns extendable \STAC Object classes.
+    #
+    # When given arguments, sets the given values as its scope.
+    def scope(*scope)
+      if scope.empty?
+        @scope ||= []
+      else
+        @scope = scope
+      end
+    end
+  end
+end

data/lib/stac/extensions/electro_optical.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../extension'
+require_relative '../item'
+
+module STAC
+  module Extensions
+    # Utilities for Electro-Optical extension.
+    #
+    # Electro-Optical \Extension Specification: https://github.com/stac-extensions/eo/
+    module ElectroOptical
+      extend Extension
+
+      identifier 'https://stac-extensions.github.io/eo/v1.0.0/schema.json'
+      scope STAC::Item
+
+      module Properties # rubocop:disable Style/Documentation
+        attr_reader :extra
+
+        def eo_bands
+          extra.fetch('eo:bands', []).map { |band_hash| Band.new(band_hash) }
+        end
+
+        def eo_bands=(bands)
+          extra['eo:bands'] = bands.map(&:to_h)
+        end
+
+        def eo_cloud_cover
+          extra['eo:cloud_cover']
+        end
+
+        def eo_cloud_cover=(cloud_cover)
+          extra['eo:cloud_cover'] = cloud_cover
+        end
+      end
+
+      module Asset
+        include Properties
+      end
+
+      # Represents \Band object of Electro-Optical extension.
+      class Band
+        attr_reader :raw_hash # :nodoc:
+
+        def initialize(raw_hash)
+          @raw_hash = raw_hash
+        end
+
+        def to_h
+          raw_hash
+        end
+
+        %i[name common_name description center_wavelength full_width_half_max].each do |field|
+          define_method(field) do
+            # @type self: Band
+            raw_hash[field.to_s]
+          end
+
+          define_method("#{field}=") do |value|
+            # @type self: Band
+            raw_hash[field.to_s] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stac/extensions/projection.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative '../extension'
+require_relative '../item'
+
+module STAC
+  module Extensions
+    # Utilities for \Projection extension.
+    #
+    # \Projection \Extension Specification: https://github.com/stac-extensions/projection/
+    module Projection
+      extend Extension
+
+      identifier 'https://stac-extensions.github.io/projection/v1.0.0/schema.json'
+      scope STAC::Item
+
+      module Properties # rubocop:disable Style/Documentation
+        attr_reader :extra
+
+        %w[
+          proj:epsg proj:wkt2 proj:projjson proj:geometry proj:bbox proj:centroid proj:shape proj:transform
+        ].each do |field|
+          method_name = field.sub(':', '_')
+
+          define_method(method_name) do
+            # @type self: Properties
+            extra[field]
+          end
+
+          define_method("#{method_name}=") do |value|
+            # @type self: Properties
+            extra[field] = value
+          end
+        end
+      end
+
+      module Asset
+        include Properties
+      end
+    end
+  end
+end