stac 0.2.0 → 0.3.0

data/lib/stac/stac_object.rb

@@ -1,49 +1,67 @@
 # frozen_string_literal: true
 
-require 'json'
 require_relative 'errors'
+require_relative 'file_writer'
+require_relative 'hash_like'
 require_relative 'link'
 require_relative 'spec_version'
 
 module STAC
-  # Base class for \STAC objects (i.e. Catalog, Collection and Item).
+  # Raised when a STAC object does not have rel="self" link HREF.
+  class NoSelfHrefError < Error
+    attr_reader :stac_object
+
+    def initialize(msg = nil, stac_object:)
+      super(msg)
+      @stac_object = stac_object
+    end
+  end
+
+  # Base class for \STAC objects (i.e. Catalog, Collection, and Item).
   class STACObject
+    include HashLike
+
+    @@extendables = {} # rubocop:disable Style/ClassVars
+
+    # Returns available extension modules.
+    def self.extendables
+      @@extendables.values.uniq
+    end
+
+    # Adds the given extension module to .extendables.
+    def self.add_extendable(extendable)
+      @@extendables[extendable.identifier] = extendable
+      self
+    end
+
     class << self
-      attr_accessor :type # :nodoc:
+      attr_reader :type # :nodoc:
 
       # Base method to deserialize shared fields from a Hash.
       #
       # Raises ArgumentError when any required fields are missing.
       def from_hash(hash)
-        raise TypeError, "type field is not '#{type}': #{hash['type']}" if hash.fetch('type') != type
+        h = hash.transform_keys(&:to_sym)
+        raise TypeError, "type field is not '#{type}': #{h[:type]}" if h.fetch(:type) != type
 
-        transformed = hash.transform_keys(&:to_sym).except(:type, :stac_version)
-        transformed[:links] = transformed.fetch(:links).map { |link| Link.from_hash(link) }
-        new(**transformed)
-      rescue KeyError => e
-        raise ArgumentError, "required field not found: #{e.key}"
+        new(**h.except(:type, :stac_version))
       end
     end
 
-    attr_accessor :stac_extensions, :extra
-
     # HTTP Client to fetch objects from HTTP HREF links.
     attr_accessor :http_client
 
-    attr_reader :links
+    attr_reader :stac_extensions, :links
 
-    def initialize(links:, stac_extensions: nil, **extra)
+    def initialize(links: [], stac_extensions: [], **extra)
       @links = []
       links.each do |link|
-        add_link(link) # to set `owner`
+        add_link(**link.transform_keys(&:to_sym)) # to set `owner`
       end
       @stac_extensions = stac_extensions
       @extra = extra.transform_keys(&:to_s)
       @http_client = STAC.default_http_client
-    end
-
-    def type
-      self.class.type
+      apply_extensions!
     end
 
     # Serializes self to a Hash.
@@ -51,34 +69,41 @@ module STAC
       {
         'type' => type,
         'stac_version' => SPEC_VERSION,
-        'stac_extensions' => stac_extensions,
+        'stac_extensions' => stac_extensions.empty? ? nil : stac_extensions,
         'links' => links.map(&:to_h),
       }.merge(extra).compact
     end
 
-    # Serializes self to a JSON string.
-    def to_json(...)
-      to_h.to_json(...)
+    def deep_dup
+      super.tap do |obj|
+        obj.http_client = http_client.dup
+      end
     end
 
-    # Adds a link with setting Link#owner as self.
-    def add_link(link)
-      link.owner = self
-      links << link
+    def type
+      self.class.type.to_s
     end
 
-    # Reterns HREF of the rel="self" link.
-    def self_href
-      find_link(rel: 'self')&.href
+    # Returns extended extension modules.
+    def extended
+      @extended ||= []
     end
 
-    # Adds a link with the give HREF as rel="self".
+    # Adds the given extension identifier to #stac_extensions.
     #
-    # When any ref="self" links already exist, removes them.
-    def self_href=(absolute_href)
-      self_link = Link.new(rel: 'self', href: absolute_href, type: 'application/json')
-      remove_link(rel: 'self')
-      add_link(self_link)
+    # When the given argument is extendable, the item extends the module.
+    def add_extension(extension)
+      case extension
+      when Extension
+        stac_extensions << extension.identifier
+        apply_extension!(extension)
+      else
+        stac_extensions << extension
+        if (extension = @@extendables[extension]) && extension.scope.include?(self.class)
+          apply_extension!(extension)
+        end
+      end
+      self
     end
 
     # Returns a link matching the arguments.
@@ -92,9 +117,86 @@ module STAC
       end
     end
 
+    # Adds a link with setting Link#owner as self.
+    #
+    # Raises ArgumentError when both target and href are not given.
+    def add_link(target = nil, rel:, href: nil, type: nil, title: nil, **extra)
+      raise ArgumentError, 'target or href must be given' if target.nil? && href.nil?
+
+      link = Link.new(target, rel: rel, href: href, type: type, title: title, **extra)
+      link.owner = self
+      links << link
+      self
+    end
+
+    # Reterns HREF of the rel="self" link.
+    def self_href
+      find_link(rel: 'self')&.href
+    end
+
+    # Overwrites rel="self" link with the given HREF.
+    #
+    # When any ref="self" links already exist, removes them.
+    def self_href=(absolute_href)
+      remove_links(rel: 'self')
+      add_link(rel: 'self', href: absolute_href, type: 'application/json')
+    end
+
+    # Returns a rel="root" link as a catalog/collection object if it exists.
+    def root
+      find_link(rel: 'root')&.target
+    end
+
+    # Overwrites rel="root" link.
+    def root=(catalog)
+      remove_links(rel: 'root')
+      add_link(catalog, rel: 'root', type: 'application/json', title: catalog.title) if catalog
+    end
+
+    # Returns a rel="parent" link as a catalog/collection object if it exists.
+    def parent
+      find_link(rel: 'parent')&.target
+    end
+
+    # Overwrites rel="parent" link.
+    def parent=(catalog)
+      remove_links(rel: 'parent')
+      add_link(catalog, rel: 'parent', type: 'application/json', title: catalog.title) if catalog
+    end
+
+    # Writes self on `dest` with the given writer.
+    #
+    # The default writer is a FileWriter.
+    def save(dest = nil, writer: FileWriter.new)
+      writer.write(to_h, dest: dest || self_href!)
+    end
+
+    protected
+
+    def self_href!
+      self_href or raise NoSelfHrefError.new('no rel="self" link href', stac_object: self)
+    end
+
     private
 
-    def remove_link(rel:)
+    def extensions
+      stac_extensions
+        .map { |extension_id| @@extendables[extension_id] }
+        .compact
+        .select { |extension| extension.scope.include?(self.class) }
+    end
+
+    def apply_extensions!
+      extensions.each do |extension|
+        apply_extension!(extension)
+      end
+    end
+
+    def apply_extension!(extension)
+      extended << extension
+    end
+
+    def remove_links(rel:)
       links.reject! { |link| link.rel == rel }
     end
   end

data/lib/stac/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module STAC
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/stac.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
-require_relative 'stac/simple_http_client'
 require_relative 'stac/object_resolver'
+require_relative 'stac/simple_http_client'
+require_relative 'stac/stac_object'
+require_relative 'stac/extensions/electro_optical'
+require_relative 'stac/extensions/projection'
+require_relative 'stac/extensions/scientific_citation'
+require_relative 'stac/extensions/view_geometry'
 require_relative 'stac/version'
 
 # Gem namespace.
@@ -27,4 +32,10 @@ module STAC
   end
 
   self.default_http_client = SimpleHTTPClient.new
+
+  STACObject
+    .add_extendable(Extensions::ElectroOptical)
+    .add_extendable(Extensions::Projection)
+    .add_extendable(Extensions::ScientificCitation)
+    .add_extendable(Extensions::ViewGeometry)
 end

data/sig/stac/asset.rbs

@@ -1,5 +1,6 @@
 module STAC
   class Asset
+    include HashLike
     include CommonMetadata
 
     def self.from_hash: (Hash[String, untyped] hash) -> Asset
@@ -9,12 +10,9 @@ module STAC
     attr_accessor description: String?
     attr_accessor type: String?
     attr_accessor roles: Array[String]?
-    attr_accessor extra: Hash[String, untyped]
 
     def initialize: (
       href: String, ?title: String?, ?description: String?, ?type: String?, ?roles: Array[String]?, **untyped
     ) -> void
-
-    def to_h: -> Hash[String, untyped]
   end
 end

data/sig/stac/catalog.rbs

@@ -1,21 +1,44 @@
 module STAC
   class Catalog < STACObject
-    def self.from_hash: (Hash[String, untyped] hash) -> Catalog
+    def self.from_hash: (Hash[String | Symbol, untyped] hash) -> Catalog
+    def self.root: (
+      id: String,
+      description: String,
+      href: String,
+      ?links: Array[Hash[String, String]],
+      ?title: String?,
+      ?stac_extensions: Array[String],
+      **untyped
+    ) -> Catalog
 
     attr_accessor id: String
     attr_accessor description: String
     attr_accessor title: String?
     
     def initialize: (
-      id: String, description: String, links: Array[Link], ?title: String?, ?stac_extensions: Array[String]?, **untyped
+      id: String,
+      description: String,
+      ?links: Array[Hash[String, String]],
+      ?title: String?,
+      ?stac_extensions: Array[String],
+      **untyped
     ) -> void
 
-    def to_h: -> Hash[String, untyped]
-    def children: -> Enumerator::Lazy[Catalog | Collection, void]
+    def children: -> Enumerator::Lazy[Catalog, void]
+    def all_children: -> Enumerator::Lazy[Catalog, void]
     def collections: -> Enumerator::Lazy[Collection, void]
-    def find_child: (String id, ?recursive: bool) -> (Catalog | Collection | nil)
+    def all_collections: -> Enumerator::Lazy[Collection, void]
+    def find_child: (String id, ?recursive: bool) -> Catalog?
     def items: -> Enumerator::Lazy[Item, void]
     def all_items: -> Enumerator::Lazy[Item, void]
     def find_item: (String id, ?recursive: bool) -> Item?
+    def add_child: (Catalog catalog, ?href: String, ?title: String?) -> self
+    def add_item: (Item item, ?href: String, ?title: String?) -> self
+    def export: (?String? dest_dir, ?writer: _Writer) -> void
+
+    private
+
+    def child_links: -> Array[Link]
+    def item_links: -> Array[Link]
   end
 end

data/sig/stac/collection.rbs

@@ -1,29 +1,37 @@
 module STAC
   class Collection < Catalog
-    def self.from_hash: (Hash[String, untyped] hash) -> Collection
+    def self.from_hash: (Hash[String | Symbol, untyped] hash) -> Collection
 
     attr_accessor license: String
     attr_accessor extent: Extent
     attr_accessor keywords: Array[String]?
     attr_accessor providers: Array[Provider]?
     attr_accessor summaries: Hash[String, untyped]?
-    attr_accessor assets: Hash[String, Asset]?
+    attr_reader assets: Hash[String, Asset]?
 
     def initialize: (
       id: String,
       description: String,
-      links: Array[Link],
       license: String,
       extent: Extent,
+      ?links: Array[Hash[String, String]],
       ?title: String?,
       ?keywords: Array[String]?,
       ?providers: Array[Provider]?,
       ?summaries: Hash[String, untyped]?,
       ?assets: Hash[String, Asset]?,
-      ?stac_extensions: Array[String]?,
+      ?stac_extensions: Array[String],
       **untyped
     ) -> void
 
-    def to_h: -> Hash[String, untyped]
+    def add_asset: (
+      key: String,
+      href: String,
+      ?title: String?,
+      ?description: String?,
+      ?type: String?,
+      ?roles: Array[String]?,
+      **untyped
+    ) -> self
   end
 end

data/sig/stac/common_metadata.rbs

@@ -1,6 +1,6 @@
 module STAC
   module CommonMetadata
-    attr_accessor extra: Hash[String, untyped]
+    attr_reader extra: Hash[String, untyped]
     
     def title: -> String?
     def title=: (String) -> void
@@ -19,7 +19,7 @@ module STAC
     def license: -> String?
     def license=: (String) -> void
     def providers: -> Array[Provider]
-    def providers=: (Array[Provider]) -> void
+    def providers=: (Array[Provider | Hash[String, untyped]]) -> void
     def platform: -> String?
     def platform=: (String) -> void
     def instruments: -> Array[String]?

data/sig/stac/errors.rbs

@@ -5,9 +5,6 @@ module STAC
   class TypeError < Error
   end
 
-  class UnknownURISchemeError < Error
-  end
-
-  class HTTPError < Error
+  class NotSupportedURISchemeError < Error
   end
 end

data/sig/stac/extension.rbs

@@ -0,0 +1,12 @@
+module STAC
+  class ExtensionWithoutIdentifierError < Error
+  end
+
+  module Extension
+    @identifier: String?
+    @scope: Array[Class]?
+
+    def identifier: -> String | (String) -> String
+    def scope: -> Array[Class] | (*Class) -> Array[Class]
+  end
+end

data/sig/stac/extensions/electro_optical.rbs

@@ -0,0 +1,40 @@
+module STAC
+  module Extensions
+    module ElectroOptical
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def eo_bands: -> Array[Band]
+        def eo_bands=: (Array[Hash[String, untyped] | Band]) -> void
+        def eo_cloud_cover: -> Numeric?
+        def eo_cloud_cover=: (Numeric) -> void
+      end
+
+      module Asset
+        include Properties
+      end
+                     
+      class Band
+        attr_reader raw_hash: Hash[String, untyped]
+
+        def initialize: (Hash[String, untyped] raw_hash) -> void
+        
+        def to_h: -> Hash[String, untyped]
+        def name: -> String?
+        def name=: (String) -> void
+        def common_name: -> String?
+        def common_name=: (String) -> void
+        def description: -> String?
+        def description=: (String) -> void
+        def center_wavelength: -> Numeric?
+        def center_wavelength=: (Numeric) -> void
+        def full_width_half_max: -> Numeric?
+        def full_width_half_max=: (Numeric) -> void
+        def solar_illumination: -> Numeric?
+        def solar_illumination=: (Numeric) -> void
+      end
+    end
+  end
+end

data/sig/stac/extensions/projection.rbs

@@ -0,0 +1,32 @@
+module STAC
+  module Extensions
+    module Projection
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def proj_epsg: -> Numeric?
+        def proj_epsg=: (Numeric) -> void
+        def proj_wkt2: -> String?
+        def proj_wkt2=: (String) -> void
+        def proj_projjson: -> Hash[String, untyped]?
+        def proj_projjson=: (Hash[String, untyped]) -> void
+        def proj_geometry: -> Hash[String, untyped]?
+        def proj_geometry=: (Hash[String, untyped]) -> void
+        def proj_bbox: -> Array[Numeric]?
+        def proj_bbox=: (Array[Numeric]) -> void
+        def proj_centroid: -> {'lat' => Numeric, 'lon' => Numeric}?
+        def proj_centroid=: ({'lat' => Numeric, 'lon' => Numeric}) -> void
+        def proj_shape: -> Array[Integer]?
+        def proj_shape=: (Array[Integer]) -> void
+        def proj_transform: -> Array[Numeric]?
+        def proj_transform=: (Array[Numeric]) -> void
+      end
+
+      module Asset
+        include Properties
+      end
+    end
+  end
+end

data/sig/stac/extensions/scientific_citation.rbs

@@ -0,0 +1,38 @@
+module STAC
+  module Extensions
+    module ScientificCitation
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def sci_doi: -> String?
+        def sci_doi=: (String) -> void
+        def sci_citation: -> String?
+        def sci_citation=: (String) -> void
+        def sci_publications: -> Array[Publication]
+        def sci_publications=: (Array[Hash[String, String] | Publication]) -> void
+      end
+
+      module Asset
+        include Properties
+      end
+
+      module Collection
+        include Properties
+      end
+
+      class Publication
+        attr_reader raw_hash: Hash[String, String]
+
+        def initialize: (Hash[String, String] raw_hash) -> void
+        
+        def to_h: -> Hash[String, String]
+        def doi: -> String?
+        def doi=: (String) -> void
+        def citation: -> String?
+        def citation=: (String) -> void
+      end
+    end
+  end
+end

data/sig/stac/extensions/view_geometry.rbs

@@ -0,0 +1,22 @@
+module STAC
+  module Extensions
+    module ViewGeometry
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def view_off_nadir: -> Numeric?
+        def view_off_nadir=: (Numeric) -> void
+        def view_incidence_angle: -> Numeric?
+        def view_incidence_angle=: (Numeric) -> void
+        def view_azimuth: -> Numeric?
+        def view_azimuth=: (Numeric) -> void
+        def view_sun_azimuth: -> Numeric?
+        def view_sun_azimuth=: (Numeric) -> void
+        def view_sun_elevation: -> Numeric?
+        def view_sun_elevation=: (Numeric) -> void
+      end
+    end
+  end
+end

data/sig/stac/extent.rbs

@@ -1,35 +1,32 @@
 module STAC
   class Extent
+    include HashLike
+
+    def self.from_hash: (Hash[String, untyped] hash) -> Extent
+
+    attr_accessor spatial: Spatial
+    attr_accessor temporal: Temporal
+
+    def initialize: (spatial: Spatial, temporal: Temporal, **untyped) -> void
+    
     class Spatial
+      include HashLike
+
       def self.from_hash: (Hash[String, untyped] hash) -> Spatial
 
       attr_accessor bbox: Array[Array[Numeric]]
-      attr_accessor extra: Hash[String, untyped]
 
       def initialize: (bbox: Array[Array[Numeric]], **untyped) -> void
-
-      def to_h: -> Hash[String, untyped]
     end
 
     class Temporal
+      include HashLike
+
       def self.from_hash: (Hash[String, untyped] hash) -> Temporal
 
       attr_accessor interval: Array[Array[String?]]
-      attr_accessor extra: Hash[String, untyped]
 
       def initialize: (interval: Array[Array[String?]], **untyped) -> void
-
-      def to_h: -> Hash[String, untyped]
     end
-
-    def self.from_hash: (Hash[String, untyped] hash) -> Extent
-
-    attr_accessor spatial: Spatial
-    attr_accessor temporal: Temporal
-    attr_accessor extra: Hash[String, untyped]
-
-    def initialize: (spatial: Spatial, temporal: Temporal, **untyped) -> void
-
-    def to_h: -> Hash[String, untyped]
   end
 end

data/sig/stac/file_writer.rbs

@@ -0,0 +1,13 @@
+module STAC
+  class FileWriter
+    @hash_to_json: ^(Hash[String, untyped]) -> String
+
+    def initialize: (?hash_to_json: ^(Hash[String, untyped]) -> String) -> void
+
+    def write: (Hash[String, untyped], dest: String) -> void
+  end
+
+  interface _Writer
+    def write: (Hash[String, untyped], dest: String) -> void
+  end
+end

data/sig/stac/hash_like.rbs

@@ -0,0 +1,13 @@
+module STAC
+  module HashLike
+    attr_reader extra: Hash[String, untyped]
+
+    def []: (String | Symbol key) -> untyped
+    def []=: (String | Symbol key, untyped value) -> untyped
+    def update: (**untyped) -> self
+    def to_hash: -> Hash[String, untyped]
+    def to_h: -> Hash[String, untyped]
+    def to_json: -> String
+    def deep_dup: -> self
+  end
+end

data/sig/stac/item.rbs

@@ -1,28 +1,37 @@
 module STAC
   class Item < STACObject
-    def self.from_hash: (Hash[String, untyped] hash) -> Item
+    def self.from_hash: (Hash[String | Symbol, untyped] hash) -> Item
 
     attr_accessor id: String
     attr_accessor geometry: Hash[String, untyped]?
-    attr_accessor properties: Properties
-    attr_accessor assets: Hash[String, Asset]
     attr_accessor bbox: Array[Numeric]?
     attr_accessor collection_id: String?
 
+    attr_reader properties: Properties
+    attr_reader assets: Hash[String, Asset]
+
     def initialize: (
       id: String,
       geometry: Hash[String, untyped]?,
       properties: Properties,
-      links: Array[Link],
-      assets: Hash[String, Asset],
+      ?links: Array[Hash[String, String]],
+      ?assets: Hash[String, Asset],
       ?bbox: Array[Numeric]?,
       ?collection: String | Collection | nil,
-      ?stac_extensions: Array[String]?,
+      ?stac_extensions: Array[String],
       **untyped
     ) -> void
 
-    def datetime: -> Time?
     def collection: -> Collection?
     def collection=: (Collection collection) -> void
+    def add_asset: (
+      key: String,
+      href: String,
+      ?title: String?,
+      ?description: String?,
+      ?type: String?,
+      ?roles: Array[String]?,
+      **untyped
+    ) -> self
   end
 end