stac 0.1.0

data/lib/stac/extent.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module STAC
+  # Represents \STAC extent object, which describes the spatio-temporal extents of a Collection.
+  #
+  # Specification: https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#extent-object
+  class Extent
+    # Describes the spatial extents of a Collection
+    class Spatial
+      # Deserializes a Spatial from a Hash.
+      def self.from_hash(hash)
+        new(**hash.transform_keys(&:to_sym))
+      end
+
+      attr_accessor :bbox, :extra
+
+      def initialize(bbox:, **extra)
+        @bbox = bbox
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      # Serializes self to a Hash.
+      def to_h
+        {
+          'bbox' => bbox,
+        }.merge(extra)
+      end
+    end
+
+    # Describes the temporal extents of a Collection.
+    class Temporal
+      # Deserializes a Temporal from a Hash.
+      def self.from_hash(hash)
+        new(**hash.transform_keys(&:to_sym))
+      end
+
+      attr_accessor :interval, :extra
+
+      def initialize(interval:, **extra)
+        @interval = interval
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      # Serializes self to a Hash.
+      def to_h
+        {
+          'interval' => interval,
+        }.merge(extra)
+      end
+    end
+
+    class << self
+      # Deserializes an Extent from a Hash.
+      def from_hash(hash)
+        transformed = hash.transform_keys(&:to_sym)
+        transformed[:spatial] = Spatial.from_hash(transformed.fetch(:spatial))
+        transformed[:temporal] = Temporal.from_hash(transformed.fetch(:temporal))
+        new(**transformed)
+      end
+    end
+
+    attr_accessor :spatial, :temporal, :extra
+
+    def initialize(spatial:, temporal:, **extra)
+      @spatial = spatial
+      @temporal = temporal
+      @extra = extra.transform_keys(&:to_s)
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      {
+        'spatial' => spatial.to_h,
+        'temporal' => temporal.to_h,
+      }.merge(extra)
+    end
+  end
+end

data/lib/stac/item.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative 'asset'
+require_relative 'errors'
+require_relative 'properties'
+require_relative 'stac_object'
+
+module STAC
+  # Represents \STAC item.
+  #
+  # \STAC \Item Specification: https://github.com/radiantearth/stac-spec/tree/master/item-spec
+  class Item < STAC::STACObject
+    self.type = 'Feature'
+
+    class << self
+      def from_hash(hash)
+        h = hash.dup
+        h['properties'] = Properties.from_hash(h.fetch('properties'))
+        h['assets'] = h.fetch('assets').transform_values { |v| Asset.from_hash(v) }
+        super(h)
+      rescue KeyError => e
+        raise ArgumentError, "required field not found: #{e.key}"
+      end
+    end
+
+    attr_accessor :geometry, :bbox, :properties, :assets, :collection_id
+
+    def initialize(
+      id:, geometry:, properties:, links:, assets:, bbox: nil, collection: nil, stac_extensions: nil, **extra
+    )
+      super(id: id, links: links, stac_extensions: stac_extensions, **extra)
+      @geometry = geometry
+      @properties = properties
+      @assets = assets
+      @bbox = bbox
+      case collection
+      when Collection
+        self.collection = collection
+      else
+        @collection_id = collection
+      end
+    end
+
+    def to_h
+      super.merge(
+        {
+          'geometry' => geometry, # required but nullable
+        },
+      ).merge(
+        {
+          'bbox' => bbox,
+          'properties' => properties.to_h,
+          'assets' => assets.transform_values(&:to_h),
+          'collection' => collection_id,
+        }.compact,
+      )
+    end
+
+    # Returns datetime from #properties.
+    def datetime
+      properties.datetime
+    end
+
+    # Returns a rel="collection" link as a collection object if it exists.
+    def collection
+      link = find_link(rel: 'collection')
+      link&.target
+    end
+
+    # Overwrites rel="collection" link and #collection_id attribute.
+    def collection=(collection)
+      raise ArgumentError, 'collection must have a rel="self" link' unless (collection_href = collection.self_href)
+
+      @collection_id = collection.id
+      collection_link = Link.new(
+        rel: 'collection',
+        href: collection_href,
+        type: 'application/json',
+        title: collection.title,
+      )
+      remove_link(rel: 'collection')
+      add_link(collection_link)
+    end
+  end
+end

data/lib/stac/link.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'uri'
+require_relative 'errors'
+
+module STAC
+  # Represents \STAC link object, which describes a relationship with another entity.
+  class Link
+    class << self
+      # Deserializes a Link from a Hash.
+      def from_hash(hash)
+        new(**hash.transform_keys(&:to_sym))
+      end
+    end
+
+    attr_accessor :rel, :href, :type, :title, :extra
+
+    # Owner object of this link.
+    attr_accessor :owner
+
+    attr_writer :resolver # :nodoc:
+
+    def initialize(rel:, href:, type: nil, title: nil, **extra)
+      @rel = rel
+      @href = href
+      @type = type
+      @title = title
+      @extra = extra.transform_keys(&:to_s)
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      {
+        'rel' => rel,
+        'href' => href,
+        'type' => type,
+        'title' => title,
+      }.merge(extra).compact
+    end
+
+    # Returns the absolute HREF for this link.
+    #
+    # When it could not assemble the absolute HREF, it returns nil.
+    def absolute_href
+      if URI(href).absolute?
+        href
+      elsif (base_href = owner&.self_href)
+        Pathname(base_href).dirname.join(href).to_s
+      end
+    end
+
+    # Returns a \STAC object resolved from HREF.
+    #
+    # When it could not assemble the absolute HREF, it returns nil.
+    def target
+      @target ||= if (url = absolute_href)
+                    object = resolver.resolve(url)
+                    object.self_href = url
+                    object
+                  end
+    end
+
+    private
+
+    def resolver
+      @resolver ||= ObjectResolver.new
+    end
+  end
+end

data/lib/stac/object_resolver.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'catalog'
+require_relative 'collection'
+require_relative 'default_http_client'
+require_relative 'errors'
+require_relative 'item'
+
+module STAC
+  # Resolves a \STAC object from a URL.
+  class ObjectResolver
+    RESOLVABLES = [Catalog, Collection, Item].freeze # :nodoc:
+
+    class << self
+      # Sets the default HTTP client.
+      #
+      # HTTP client must implement method `get: (URI uri) -> String,` which fetches the URI resource through HTTP.
+      attr_writer :default_http_client
+
+      # Returns the default HTTP client.
+      def default_http_client
+        @default_http_client ||= DefaultHTTPClient.new
+      end
+    end
+
+    attr_reader :http_client
+
+    def initialize(http_client: self.class.default_http_client)
+      @http_client = http_client
+    end
+
+    # Reads a JSON from the given URL and returns a \STAC object resolved from it.
+    #
+    # Supports the following URL scheme:
+    # - http
+    # - https
+    # - file
+    #
+    # Raises:
+    # - STAC::UnknownURISchemeError when a URL with unsupported scheme was given
+    # - STAC::TypeError when it could not resolve any \STAC objects
+    def resolve(url)
+      str = read(url)
+      hash = JSON.parse(str)
+      klass = RESOLVABLES.find { |c| c.type == hash['type'] }
+      raise TypeError, "unknown STAC object type: #{hash['type']}" unless klass
+
+      klass.from_hash(hash)
+    end
+
+    private
+
+    def read(url)
+      uri = URI.parse(url)
+      case uri
+      when URI::HTTP
+        http_client.get(uri)
+      when URI::File
+        File.read(uri.path.to_s)
+      else
+        raise UnknownURISchemeError, "unknown URI scheme: #{url}"
+      end
+    end
+  end
+end

data/lib/stac/properties.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module STAC
+  # Represents \STAC properties object, which is additional metadata for Item.
+  #
+  # Specification: https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#properties-object
+  class Properties
+    class << self
+      # Deserializes a Properties from a Hash.
+      def from_hash(hash)
+        h = hash.transform_keys(&:to_sym)
+        h[:datetime] = h[:datetime] ? Time.iso8601(h[:datetime]) : nil
+        new(**h)
+      end
+    end
+
+    attr_accessor :datetime, :extra
+
+    def initialize(datetime:, **extra)
+      @datetime = datetime
+      @extra = extra.transform_keys(&:to_s)
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      {
+        'datetime' => datetime&.iso8601,
+      }.merge(extra)
+    end
+  end
+end

data/lib/stac/provider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module STAC
+  # Represents \STAC provider object, which provides information about a provider.
+  #
+  # Specicication: https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#provider-object
+  class Provider
+    class << self
+      # Deserializes a Provider from a Hash.
+      def from_hash(hash)
+        new(**hash.transform_keys(&:to_sym))
+      end
+    end
+
+    attr_accessor :name, :description, :roles, :url, :extra
+
+    def initialize(name:, description: nil, roles: nil, url: nil, **extra)
+      @name = name
+      @description = description
+      @roles = roles
+      @url = url
+      @extra = extra.transform_keys(&:to_s)
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      {
+        'name' => name,
+        'description' => description,
+        'roles' => roles,
+        'url' => url,
+      }.merge(extra).compact
+    end
+  end
+end

data/lib/stac/spec_version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module STAC
+  SPEC_VERSION = '1.0.0'
+end

data/lib/stac/stac_object.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'errors'
+require_relative 'link'
+require_relative 'spec_version'
+
+module STAC
+  # Base class for \STAC objects (i.e. Catalog, Collection and Item).
+  class STACObject
+    class << self
+      attr_accessor :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 'Catalog': #{hash['type']}" if hash.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}"
+      end
+    end
+
+    attr_accessor :id, :stac_extensions, :extra
+
+    attr_reader :links
+
+    def initialize(id:, links:, stac_extensions: nil, **extra)
+      @id = id
+      @links = []
+      links.each do |link|
+        add_link(link) # to set `owner`
+      end
+      @stac_extensions = stac_extensions
+      @extra = extra.transform_keys(&:to_s)
+    end
+
+    def type
+      self.class.type
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      {
+        'type' => type,
+        'stac_version' => SPEC_VERSION,
+        'stac_extensions' => stac_extensions,
+        'id' => id,
+        'links' => links.map(&:to_h),
+      }.merge(extra).compact
+    end
+
+    # Serializes self to a JSON string.
+    def to_json(...)
+      to_h.to_json(...)
+    end
+
+    # Adds a link with setting Link#owner as self.
+    def add_link(link)
+      link.owner = self
+      links << link
+    end
+
+    # Reterns HREF of the rel="self" link.
+    def self_href
+      find_link(rel: 'self')&.href
+    end
+
+    # Adds a link with the give HREF as rel="self".
+    #
+    # 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)
+    end
+
+    private
+
+    def find_link(rel:)
+      links.find { |link| link.rel == rel }
+    end
+
+    def remove_link(rel:)
+      links.reject! { |link| link.rel == rel }
+    end
+  end
+end

data/lib/stac/version.rb

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

data/lib/stac.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'stac/object_resolver'
+require_relative 'stac/version'
+
+# Gem namespace.
+#
+# Provides some utility methods.
+module STAC
+  class << self
+    # Returns a \STAC object resolved from the given file path.
+    def from_file(path)
+      from_url("file://#{File.expand_path(path)}")
+    end
+
+    # Returns a \STAC object resolved from the given URL.
+    #
+    # When the resolved object does not have rel="self" link, adds a rel="self" link with the give url.
+    def from_url(url, resolver: ObjectResolver.new)
+      object = resolver.resolve(url)
+      object.self_href = url unless object.self_href
+      object
+    end
+  end
+end

data/sig/open-uri.rbs

@@ -0,0 +1,8 @@
+module OpenURI
+  class HTTPError < StandardError
+  end
+end
+
+module URI
+  def read: (?Hash[String, String] options) -> String
+end

data/sig/stac/asset.rbs

@@ -0,0 +1,18 @@
+module STAC
+  class Asset
+    def self.from_hash: (Hash[String, untyped] hash) -> Asset
+
+    attr_accessor href: String
+    attr_accessor title: String?
+    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

@@ -0,0 +1,20 @@
+module STAC
+  class Catalog < STACObject
+    def self.from_hash: (Hash[String, untyped] hash) -> Catalog
+
+    attr_accessor description: String
+    attr_accessor title: String?
+    
+    def initialize: (
+      id: String, description: String, links: Array[Link], ?title: String?, ?stac_extensions: Array[String]?, **untyped
+    ) -> void
+
+    def to_h: -> Hash[String, untyped]
+    def children: -> Enumerator::Lazy[Catalog | Collection, void]
+    def collections: -> Enumerator::Lazy[Collection, void]
+    def find_child: (String id, ?recursive: bool) -> (Catalog | Collection | nil)
+    def items: -> Enumerator::Lazy[Item, void]
+    def all_items: -> Enumerator::Lazy[Item, void]
+    def find_item: (String id, ?recursive: bool) -> Item?
+  end
+end

data/sig/stac/collection.rbs

@@ -0,0 +1,29 @@
+module STAC
+  class Collection < Catalog
+    def self.from_hash: (Hash[String, 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]?
+
+    def initialize: (
+      id: String,
+      description: String,
+      links: Array[Link],
+      license: String,
+      extent: Extent,
+      ?title: String?,
+      ?keywords: Array[String]?,
+      ?providers: Array[Provider]?,
+      ?summaries: Hash[String, untyped]?,
+      ?assets: Hash[String, Asset]?,
+      ?stac_extensions: Array[String]?,
+      **untyped
+    ) -> void
+
+    def to_h: -> Hash[String, untyped]
+  end
+end

data/sig/stac/default_http_client.rbs

@@ -0,0 +1,9 @@
+module STAC
+  class DefaultHTTPClient
+    attr_reader options: Hash[String, String]
+
+    def initialize: (?Hash[String, String] options) -> void
+
+    def get: (URI uri) -> String
+  end
+end

data/sig/stac/errors.rbs

@@ -0,0 +1,13 @@
+module STAC
+  class Error < StandardError
+  end
+
+  class TypeError < Error
+  end
+
+  class UnknownURISchemeError < Error
+  end
+
+  class HTTPError < Error
+  end
+end

data/sig/stac/extent.rbs

@@ -0,0 +1,35 @@
+module STAC
+  class Extent
+    class Spatial
+      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
+      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/item.rbs

@@ -0,0 +1,27 @@
+module STAC
+  class Item < STACObject
+    def self.from_hash: (Hash[String, untyped] hash) -> Item
+
+    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?
+
+    def initialize: (
+      id: String,
+      geometry: Hash[String, untyped]?,
+      properties: Properties,
+      links: Array[Link],
+      assets: Hash[String, Asset],
+      ?bbox: Array[Numeric]?,
+      ?collection: String | Collection | nil,
+      ?stac_extensions: Array[String]?,
+      **untyped
+    ) -> void
+
+    def datetime: -> Time?
+    def collection: -> Collection?
+    def collection=: (Collection collection) -> void
+  end
+end

data/sig/stac/link.rbs

@@ -0,0 +1,24 @@
+module STAC
+  class Link
+    def self.from_hash: (Hash[String, untyped]) -> Link
+
+    attr_accessor rel: String
+    attr_accessor href: String
+    attr_accessor type: String?
+    attr_accessor title: String?
+    attr_accessor extra: Hash[String, untyped]
+    attr_accessor owner: STACObject | nil
+    @target: Catalog | Collection | Item | nil
+    @resolver: ObjectResolver
+
+    def initialize: (rel: String, href: String, ?type: String?, ?title: String?, **untyped) -> void
+
+    def to_h: -> Hash[String, untyped]
+    def absolute_href: -> String?
+    def target: -> (Catalog | Collection | Item | nil)
+
+    private
+
+    def resolver: -> ObjectResolver
+  end
+end