gsplat 1.0.0

data/lib/gsplat/io/npy.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+require_relative "zip_archive"
+
+module Gsplat
+  # File formats and dataset readers used by training and interchange.
+  module IO
+    # NumPy v1.0 NPY and NPZ interoperability.
+    module Npy
+      # Binary prefix defined by the NumPy NPY format.
+      MAGIC = "\x93NUMPY".b
+      # NPY format version emitted and accepted by this codec.
+      VERSION = [1, 0].freeze
+      # Header byte alignment used by NPY v1.0.
+      HEADER_ALIGNMENT = 64
+      # Mapping from supported Numo types to NumPy descriptors and pack formats.
+      DESCRIPTORS = {
+        Numo::SFloat => ["<f4", "e*", 4],
+        Numo::DFloat => ["<f8", "E*", 8],
+        Numo::UInt8 => ["|u1", "C*", 1],
+        Numo::UInt16 => ["<u2", "S<*", 2],
+        Numo::Int32 => ["<i4", "l<*", 4],
+        Numo::Int64 => ["<i8", "q<*", 8],
+        Numo::Bit => ["|b1", "C*", 1]
+      }.freeze
+      # Reverse descriptor-to-Numo type mapping.
+      TYPES = DESCRIPTORS.to_h { |type, metadata| [metadata.first, type] }.freeze
+
+      module_function
+
+      # Reads an NPY v1.0 array.
+      #
+      # @param source [String, #read] path or binary IO
+      # @return [Numo::NArray]
+      def read(source)
+        decode(read_bytes(source))
+      end
+
+      # Writes an NPY v1.0 array in C order.
+      #
+      # @param target [String, #write] path or binary IO
+      # @param array [Numo::NArray]
+      # @return [Integer] bytes written
+      def write(target, array)
+        write_bytes(target, encode(array))
+      end
+
+      # Reads all arrays from an NPZ archive.
+      #
+      # @param source [String, #read] path or binary IO
+      # @return [Hash{String=>Numo::NArray}]
+      def read_npz(source)
+        ZipArchive.decode(read_bytes(source)).each_with_object({}) do |(name, data), arrays|
+          next unless name.end_with?(".npy")
+
+          arrays[name.delete_suffix(".npy")] = decode(data)
+        end
+      end
+
+      # Writes arrays to an NPZ archive.
+      #
+      # @param target [String, #write] path or binary IO
+      # @param arrays [Hash{String, Symbol=>Numo::NArray}]
+      # @param compression [Symbol] :deflate or :stored
+      # @return [Integer] bytes written
+      def write_npz(target, arrays, compression: :deflate)
+        entries = arrays.to_h do |name, array|
+          normalized = normalize_entry_name(name)
+          ["#{normalized}.npy", encode(array)]
+        end
+        write_bytes(target, ZipArchive.encode(entries, compression: compression))
+      end
+
+      # Returns the NumPy dtype descriptor for a Numo type.
+      #
+      # @param type [Class]
+      # @return [String]
+      def descriptor_for(type)
+        DESCRIPTORS.fetch(type) do
+          raise NotSupportedError, "unsupported Numo dtype #{type}"
+        end.first
+      end
+
+      def encode(array)
+        descriptor, pack_format, = DESCRIPTORS.fetch(array.class) do
+          raise NotSupportedError, "unsupported Numo dtype #{array.class}"
+        end
+        header = build_header(descriptor, array.shape)
+        values = array.to_a
+        values = values.is_a?(Array) ? values.flatten : [values]
+
+        MAGIC + VERSION.pack("C2") + [header.bytesize].pack("v") + header + values.pack(pack_format)
+      end
+      private_class_method :encode
+
+      def decode(data)
+        data = data.b
+        raise Gsplat::Error, "invalid NPY magic" unless data.start_with?(MAGIC)
+
+        version = byteslice!(data, 6, 2).unpack("C2")
+        raise NotSupportedError, "unsupported NPY version #{version.join('.')}" unless version == VERSION
+
+        header_length = byteslice!(data, 8, 2).unpack1("v")
+        header = byteslice!(data, 10, header_length)
+        descriptor, shape = parse_header(header)
+        type, pack_format, byte_width = dtype_metadata(descriptor)
+        count = shape.empty? ? 1 : shape.inject(:*)
+        payload = byteslice!(data, 10 + header_length, count * byte_width)
+        values = payload.unpack(pack_format)
+
+        return type.cast(values.first) if shape.empty?
+
+        type.cast(values).reshape(*shape)
+      end
+      private_class_method :decode
+
+      def build_header(descriptor, shape)
+        shape_text = if shape.empty?
+                       ""
+                     elsif shape.length == 1
+                       "#{shape.first},"
+                     else
+                       shape.join(", ")
+                     end
+        dictionary = "{'descr': '#{descriptor}', 'fortran_order': False, 'shape': (#{shape_text}), }"
+        padding = (HEADER_ALIGNMENT - ((10 + dictionary.bytesize + 1) % HEADER_ALIGNMENT)) % HEADER_ALIGNMENT
+        header = "#{dictionary}#{' ' * padding}\n"
+        raise NotSupportedError, "NPY v1.0 header exceeds 65535 bytes" if header.bytesize > 65_535
+
+        header.b
+      end
+      private_class_method :build_header
+
+      def parse_header(header)
+        descriptor = header[/(?:'|")descr(?:'|"):\s*(?:'|")([^'"]+)(?:'|")/, 1]
+        order = header[/(?:'|")fortran_order(?:'|"):\s*(True|False)/, 1]
+        shape_text = header[/(?:'|")shape(?:'|"):\s*\(([^)]*)\)/, 1]
+        raise Gsplat::Error, "invalid NPY header" unless descriptor && order && shape_text
+        raise NotSupportedError, "Fortran order NPY arrays are unsupported" if order == "True"
+
+        shape = shape_text.scan(/\d+/).map!(&:to_i)
+        [descriptor, shape]
+      end
+      private_class_method :parse_header
+
+      def dtype_metadata(descriptor)
+        type = TYPES.fetch(descriptor) do
+          raise NotSupportedError, "unsupported NumPy dtype #{descriptor.inspect}"
+        end
+        [type, *DESCRIPTORS.fetch(type).drop(1)]
+      end
+      private_class_method :dtype_metadata
+
+      def normalize_entry_name(name)
+        normalized = name.to_s.delete_suffix(".npy")
+        if normalized.empty? || normalized.match?(%r{[/\\]}) || normalized.include?("\0")
+          raise ArgumentError, "invalid NPZ entry name #{name.inspect}"
+        end
+
+        normalized
+      end
+      private_class_method :normalize_entry_name
+
+      def read_bytes(source)
+        return source.read.b if source.respond_to?(:read)
+
+        File.binread(source)
+      end
+      private_class_method :read_bytes
+
+      def write_bytes(target, data)
+        return target.write(data) if target.respond_to?(:write)
+
+        File.binwrite(target, data)
+      end
+      private_class_method :write_bytes
+
+      def byteslice!(data, offset, length)
+        slice = data.byteslice(offset, length)
+        return slice if slice&.bytesize == length
+
+        raise Gsplat::Error, "truncated NPY data"
+      end
+      private_class_method :byteslice!
+    end
+  end
+end

data/lib/gsplat/io/ply.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "ply_reader"
+
+module Gsplat
+  module IO
+    # Inria-compatible Gaussian-splat PLY input and output.
+    module Ply
+      # Leading vertex properties in the Inria layout.
+      BASE_PROPERTIES = %w[x y z nx ny nz].freeze
+      # Properties following spherical-harmonic coefficients.
+      TRAILING_PROPERTIES = %w[opacity scale_0 scale_1 scale_2 rot_0 rot_1 rot_2 rot_3].freeze
+      # Minimum property set required for a readable Gaussian model.
+      REQUIRED_PROPERTIES = (%w[x y z] + %w[f_dc_0 f_dc_1 f_dc_2] + TRAILING_PROPERTIES).freeze
+
+      module_function
+
+      # Writes raw Gaussian parameters with the Inria property layout.
+      #
+      # @param target [String, #write] output path or binary IO
+      # @param params [Hash] means, scales, quats, opacities, sh0 and shN
+      # @param format [Symbol] :binary_little_endian or :ascii
+      # @return [Integer] bytes written
+      def write(target, params, format: :binary_little_endian)
+        arrays = normalize_params(params)
+        rows = parameter_rows(arrays).select { |row| row.all?(&:finite?) }
+        properties = property_names(arrays.fetch(:shN).shape[1])
+        header = build_header(format, rows.length, properties)
+        payload = encode_rows(rows, format)
+        write_bytes(target, header + payload)
+      end
+
+      # Reads Inria-layout Gaussian parameters from ASCII or little-endian PLY.
+      #
+      # @param source [String, #read] input path or IO
+      # @return [Hash{Symbol=>Numo::SFloat}]
+      def read(source)
+        columns = PlyReader.decode(read_bytes(source))
+        missing = REQUIRED_PROPERTIES - columns.keys
+        raise Gsplat::Error, "missing PLY properties: #{missing.join(', ')}" unless missing.empty?
+
+        build_params(columns)
+      end
+
+      def normalize_params(params)
+        required = %i[means scales quats opacities sh0 shN]
+        missing = required - params.keys
+        raise ArgumentError, "missing PLY params: #{missing.join(', ')}" unless missing.empty?
+
+        arrays = required.to_h { |key| [key, Ops::TensorOps.data(params.fetch(key))] }
+        count = arrays.fetch(:means).shape[0]
+        expected = {
+          means: [count, 3],
+          scales: [count, 3],
+          quats: [count, 4],
+          opacities: [count],
+          sh0: [count, 1, 3]
+        }
+        invalid = expected.find { |key, shape| arrays.fetch(key).shape != shape }
+        if invalid
+          raise ShapeError,
+                "expected #{invalid[0]} #{invalid[1].inspect}, got #{arrays.fetch(invalid[0]).shape.inspect}"
+        end
+
+        shn = arrays.fetch(:shN)
+        unless shn.ndim == 3 && shn.shape[0] == count && shn.shape[2] == 3
+          raise ShapeError, "expected shN [#{count},K,3], got #{shn.shape.inspect}"
+        end
+
+        arrays
+      end
+      private_class_method :normalize_params
+
+      def parameter_rows(arrays)
+        count = arrays.fetch(:means).shape[0]
+        count.times.map do |index|
+          [
+            *arrays.fetch(:means)[index, true].to_a.map(&:to_f),
+            0.0, 0.0, 0.0,
+            *channel_major_sh(arrays.fetch(:sh0), index),
+            *channel_major_sh(arrays.fetch(:shN), index),
+            arrays.fetch(:opacities)[index].to_f,
+            *arrays.fetch(:scales)[index, true].to_a.map(&:to_f),
+            *arrays.fetch(:quats)[index, true].to_a.map(&:to_f)
+          ]
+        end
+      end
+      private_class_method :parameter_rows
+
+      def channel_major_sh(array, index)
+        3.times.flat_map do |channel|
+          array.shape[1].times.map { |coefficient| array[index, coefficient, channel].to_f }
+        end
+      end
+      private_class_method :channel_major_sh
+
+      def property_names(rest_count)
+        direct = 3.times.map { |index| "f_dc_#{index}" }
+        rest = (rest_count * 3).times.map { |index| "f_rest_#{index}" }
+        BASE_PROPERTIES + direct + rest + TRAILING_PROPERTIES
+      end
+      private_class_method :property_names
+
+      def build_header(format, count, properties)
+        unless %i[binary_little_endian ascii].include?(format)
+          raise NotSupportedError, "unsupported PLY output format #{format.inspect}"
+        end
+
+        lines = ["ply", "format #{format} 1.0", "element vertex #{count}"]
+        lines.concat(properties.map { |name| "property float #{name}" })
+        lines << "end_header"
+        "#{lines.join("\n")}\n".b
+      end
+      private_class_method :build_header
+
+      def encode_rows(rows, format)
+        return rows.flatten.pack("e*") if format == :binary_little_endian
+
+        rows.map { |row| row.map { |value| format("%.9g", value) }.join(" ") }.join("\n").concat("\n").b
+      end
+      private_class_method :encode_rows
+
+      def build_params(columns)
+        count = columns.fetch("x").length
+        validate_column_lengths!(columns, count)
+        rest_names = indexed_names(columns, "f_rest")
+        raise Gsplat::Error, "f_rest property count must be divisible by 3" unless (rest_names.length % 3).zero?
+
+        rest_count = rest_names.length / 3
+        {
+          means: matrix(columns, %w[x y z]),
+          scales: matrix(columns, %w[scale_0 scale_1 scale_2]),
+          quats: matrix(columns, %w[rot_0 rot_1 rot_2 rot_3]),
+          opacities: Numo::SFloat.cast(columns.fetch("opacity")),
+          sh0: sh_array(columns, 1, %w[f_dc_0 f_dc_1 f_dc_2]),
+          shN: sh_array(columns, rest_count, rest_names)
+        }
+      end
+      private_class_method :build_params
+
+      def matrix(columns, names)
+        values = columns.fetch(names.first).length.times.flat_map do |index|
+          names.map { |name| columns.fetch(name)[index] }
+        end
+        Numo::SFloat.cast(values).reshape(columns.fetch(names.first).length, names.length)
+      end
+      private_class_method :matrix
+
+      def sh_array(columns, coefficient_count, names)
+        count = columns.fetch("x").length
+        output = Numo::SFloat.zeros(count, coefficient_count, 3)
+        3.times do |channel|
+          coefficient_count.times do |coefficient|
+            name = names.fetch((channel * coefficient_count) + coefficient)
+            output[true, coefficient, channel] = Numo::SFloat.cast(columns.fetch(name))
+          end
+        end
+        output
+      end
+      private_class_method :sh_array
+
+      def indexed_names(columns, prefix)
+        names = columns.keys.grep(/\A#{Regexp.escape(prefix)}_\d+\z/)
+        names.sort_by { |name| Integer(name.split("_").last, 10) }
+      end
+      private_class_method :indexed_names
+
+      def validate_column_lengths!(columns, count)
+        invalid = columns.find { |_name, values| values.length != count }
+        raise Gsplat::Error, "inconsistent PLY column #{invalid[0]}" if invalid
+      end
+      private_class_method :validate_column_lengths!
+
+      def read_bytes(source)
+        source.respond_to?(:read) ? source.read.b : File.binread(source)
+      end
+      private_class_method :read_bytes
+
+      def write_bytes(target, data)
+        target.respond_to?(:write) ? target.write(data) : File.binwrite(target, data)
+      end
+      private_class_method :write_bytes
+    end
+  end
+end

data/lib/gsplat/io/ply_reader.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Gsplat
+  module IO
+    # Header and scalar payload decoder for PLY files.
+    module PlyReader
+      Element = Data.define(:name, :count, :properties)
+      Property = Data.define(:name, :type, :count_type)
+      TYPE_FORMATS = {
+        "char" => ["c", 1], "int8" => ["c", 1],
+        "uchar" => ["C", 1], "uint8" => ["C", 1],
+        "short" => ["s<", 2], "int16" => ["s<", 2],
+        "ushort" => ["S<", 2], "uint16" => ["S<", 2],
+        "int" => ["l<", 4], "int32" => ["l<", 4],
+        "uint" => ["L<", 4], "uint32" => ["L<", 4],
+        "float" => ["e", 4], "float32" => ["e", 4],
+        "double" => ["E", 8], "float64" => ["E", 8]
+      }.freeze
+
+      module_function
+
+      def decode(data)
+        header, payload = split_header(data.b)
+        format, elements = parse_header(header)
+        columns = vertex_columns(elements)
+        reader = payload_reader(payload, format)
+        decode_elements(reader, elements, columns)
+        columns
+      end
+
+      def split_header(data)
+        match = /\A.*?end_header\r?\n/m.match(data)
+        raise Gsplat::Error, "PLY end_header is missing" unless match
+
+        [match[0], data.byteslice(match[0].bytesize..)]
+      end
+      private_class_method :split_header
+
+      def parse_header(header)
+        lines = header.lines(chomp: true).map { |line| line.delete_suffix("\r") }
+        raise Gsplat::Error, "invalid PLY magic" unless lines.shift == "ply"
+
+        format = nil
+        elements = []
+        lines.each do |line|
+          parts = line.split
+          case parts.first
+          when "format" then format = parse_format(parts)
+          when "element" then elements << parse_element(parts)
+          when "property" then elements.last.properties << parse_property(parts)
+          end
+        end
+        raise Gsplat::Error, "PLY format declaration is missing" unless format
+        raise Gsplat::Error, "PLY vertex element is missing" unless elements.any? { |item| item.name == "vertex" }
+
+        [format, elements]
+      end
+      private_class_method :parse_header
+
+      def parse_format(parts)
+        raise NotSupportedError, "unsupported PLY version #{parts[2]}" unless parts[2] == "1.0"
+        return parts[1].to_sym if %w[ascii binary_little_endian].include?(parts[1])
+
+        raise NotSupportedError, "unsupported PLY format #{parts[1].inspect}"
+      end
+      private_class_method :parse_format
+
+      def parse_element(parts)
+        raise Gsplat::Error, "invalid PLY element declaration" unless parts.length == 3
+
+        Element.new(name: parts[1], count: Integer(parts[2], 10), properties: [])
+      end
+      private_class_method :parse_element
+
+      def parse_property(parts)
+        if parts[1] == "list"
+          validate_type!(parts[2])
+          validate_type!(parts[3])
+          return Property.new(name: parts[4], type: parts[3], count_type: parts[2])
+        end
+        validate_type!(parts[1])
+        Property.new(name: parts[2], type: parts[1], count_type: nil)
+      end
+      private_class_method :parse_property
+
+      def validate_type!(type)
+        return if TYPE_FORMATS.key?(type)
+
+        raise NotSupportedError, "unsupported PLY property type #{type.inspect}"
+      end
+      private_class_method :validate_type!
+
+      def vertex_columns(elements)
+        vertex = elements.find { |element| element.name == "vertex" }
+        vertex.properties.reject(&:count_type).to_h { |property| [property.name, []] }
+      end
+      private_class_method :vertex_columns
+
+      def payload_reader(payload, format)
+        return payload.split.each if format == :ascii
+
+        StringIO.new(payload)
+      end
+      private_class_method :payload_reader
+
+      def decode_elements(reader, elements, columns)
+        elements.each do |element|
+          element.count.times do
+            element.properties.each do |property|
+              value = read_property(reader, property)
+              columns[property.name] << value if element.name == "vertex" && !property.count_type
+            end
+          end
+        end
+      rescue EOFError, StopIteration
+        raise Gsplat::Error, "truncated PLY payload"
+      end
+      private_class_method :decode_elements
+
+      def read_property(reader, property)
+        return read_scalar(reader, property.type) unless property.count_type
+
+        count = read_scalar(reader, property.count_type).to_i
+        Array.new(count) { read_scalar(reader, property.type) }
+      end
+      private_class_method :read_property
+
+      def read_scalar(reader, type)
+        return Float(reader.next) unless reader.is_a?(StringIO)
+
+        format, width = TYPE_FORMATS.fetch(type)
+        bytes = reader.read(width)
+        raise EOFError unless bytes&.bytesize == width
+
+        bytes.unpack1(format)
+      end
+      private_class_method :read_scalar
+    end
+  end
+end

data/lib/gsplat/io/zip_archive.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Gsplat
+  module IO
+    # Minimal single-disk ZIP reader/writer for NPZ archives.
+    module ZipArchive
+      LOCAL_SIGNATURE = 0x04034B50
+      CENTRAL_SIGNATURE = 0x02014B50
+      END_SIGNATURE = 0x06054B50
+      UTF8_FLAG = 0x0800
+      METHODS = { stored: 0, deflate: 8 }.freeze
+      LOCAL_TEMPLATE = "VvvvvvVVVvv"
+      CENTRAL_TEMPLATE = "VvvvvvvVVVvvvvvVV"
+      END_TEMPLATE = "VvvvvVVv"
+
+      module_function
+
+      # Encodes named binary entries as a ZIP archive.
+      #
+      # @param entries [Hash{String=>String}]
+      # @param compression [Symbol] :stored or :deflate
+      # @return [String] ZIP bytes
+      def encode(entries, compression: :deflate)
+        method = METHODS.fetch(compression) do
+          raise ArgumentError, "unknown compression #{compression.inspect}; expected stored or deflate"
+        end
+        body = +"".b
+        central = +"".b
+
+        entries.each do |name, data|
+          name = name.to_s.b
+          data = data.b
+          compressed = method.zero? ? data : deflate(data)
+          metadata = entry_metadata(name, data, compressed, method, body.bytesize)
+          body << local_header(metadata) << name << compressed
+          central << central_header(metadata) << name
+        end
+
+        central_offset = body.bytesize
+        body << central
+        body << end_record(entries.length, central.bytesize, central_offset)
+      end
+
+      # Decodes named binary entries from a ZIP archive.
+      #
+      # @param archive [String] ZIP bytes
+      # @return [Hash{String=>String}]
+      def decode(archive)
+        archive = archive.b
+        entry_count, central_offset = end_metadata(archive)
+        cursor = central_offset
+
+        entry_count.times.each_with_object({}) do |_, entries|
+          metadata, cursor = parse_central_entry(archive, cursor)
+          entries[metadata.fetch(:name)] = extract_entry(archive, metadata)
+        end
+      end
+
+      def entry_metadata(name, data, compressed, method, offset)
+        {
+          name: name,
+          method: method,
+          crc: Zlib.crc32(data),
+          compressed_size: compressed.bytesize,
+          size: data.bytesize,
+          offset: offset
+        }
+      end
+      private_class_method :entry_metadata
+
+      def local_header(metadata)
+        [
+          LOCAL_SIGNATURE, 20, UTF8_FLAG, metadata.fetch(:method), 0, 0,
+          metadata.fetch(:crc), metadata.fetch(:compressed_size), metadata.fetch(:size),
+          metadata.fetch(:name).bytesize, 0
+        ].pack(LOCAL_TEMPLATE)
+      end
+      private_class_method :local_header
+
+      def central_header(metadata)
+        [
+          CENTRAL_SIGNATURE, 20, 20, UTF8_FLAG, metadata.fetch(:method), 0, 0,
+          metadata.fetch(:crc), metadata.fetch(:compressed_size), metadata.fetch(:size),
+          metadata.fetch(:name).bytesize, 0, 0, 0, 0, 0, metadata.fetch(:offset)
+        ].pack(CENTRAL_TEMPLATE)
+      end
+      private_class_method :central_header
+
+      def end_record(entry_count, central_size, central_offset)
+        [
+          END_SIGNATURE, 0, 0, entry_count, entry_count, central_size, central_offset, 0
+        ].pack(END_TEMPLATE)
+      end
+      private_class_method :end_record
+
+      def end_metadata(archive)
+        offset = archive.rindex([END_SIGNATURE].pack("V"))
+        raise Gsplat::Error, "invalid ZIP archive: end record not found" unless offset
+
+        fields = byteslice!(archive, offset, 22).unpack(END_TEMPLATE)
+        raise Gsplat::Error, "multi-disk ZIP archives are unsupported" unless fields[1].zero? && fields[2].zero?
+
+        [fields[4], fields[6]]
+      end
+      private_class_method :end_metadata
+
+      def parse_central_entry(archive, cursor)
+        fields = byteslice!(archive, cursor, 46).unpack(CENTRAL_TEMPLATE)
+        raise Gsplat::Error, "invalid ZIP central directory" unless fields[0] == CENTRAL_SIGNATURE
+
+        name_length, extra_length, comment_length = fields.values_at(10, 11, 12)
+        name = byteslice!(archive, cursor + 46, name_length).force_encoding(Encoding::UTF_8)
+        metadata = {
+          name: name,
+          flags: fields[3],
+          method: fields[4],
+          crc: fields[7],
+          compressed_size: fields[8],
+          size: fields[9],
+          offset: fields[16]
+        }
+        [metadata, cursor + 46 + name_length + extra_length + comment_length]
+      end
+      private_class_method :parse_central_entry
+
+      def extract_entry(archive, metadata)
+        raise NotSupportedError, "encrypted ZIP entries are unsupported" unless metadata.fetch(:flags).nobits?(1)
+
+        offset = metadata.fetch(:offset)
+        fields = byteslice!(archive, offset, 30).unpack(LOCAL_TEMPLATE)
+        raise Gsplat::Error, "invalid ZIP local header" unless fields[0] == LOCAL_SIGNATURE
+
+        data_offset = offset + 30 + fields[9] + fields[10]
+        compressed = byteslice!(archive, data_offset, metadata.fetch(:compressed_size))
+        data = inflate_entry(compressed, metadata.fetch(:method))
+        validate_entry!(data, metadata)
+        data
+      end
+      private_class_method :extract_entry
+
+      def inflate_entry(data, method)
+        return data if method.zero?
+        return inflate(data) if method == METHODS.fetch(:deflate)
+
+        raise NotSupportedError, "ZIP compression method #{method} is unsupported"
+      end
+      private_class_method :inflate_entry
+
+      def validate_entry!(data, metadata)
+        return if data.bytesize == metadata.fetch(:size) && Zlib.crc32(data) == metadata.fetch(:crc)
+
+        raise Gsplat::Error, "corrupt ZIP entry #{metadata.fetch(:name).inspect}"
+      end
+      private_class_method :validate_entry!
+
+      def deflate(data)
+        stream = Zlib::Deflate.new(Zlib::DEFAULT_COMPRESSION, -Zlib::MAX_WBITS)
+        stream.deflate(data, Zlib::FINISH)
+      ensure
+        stream&.close
+      end
+      private_class_method :deflate
+
+      def inflate(data)
+        stream = Zlib::Inflate.new(-Zlib::MAX_WBITS)
+        stream.inflate(data)
+      ensure
+        stream&.close
+      end
+      private_class_method :inflate
+
+      def byteslice!(data, offset, length)
+        slice = data.byteslice(offset, length)
+        return slice if slice&.bytesize == length
+
+        raise Gsplat::Error, "truncated ZIP archive"
+      end
+      private_class_method :byteslice!
+    end
+  end
+end