feat: replace narray with numo-narray

[Oleksii Leonov (oleksii-leonov)]

Depends on #151 -- this branch is stacked on test/pin-dataset-to-na-narray-behavior; once #151 merges, the diff here shrinks to the single port commit.

Replacing narray with numo-narray. The narray gem is C code unmaintained for 10 years; numo-narray is its maintained successor. This is a breaking change for consumers -- #151 pins the old behavior in specs first, so every observable change shows up in this PR as an explicit spec diff rather than silent semantics drift.

Behavior changes (each visible as a spec diff)

API	narray (old)	numo-narray (new)
RasterBand#to_na shape	[x, y]	[y, x] (row-major)
to_na(:GDT_UInt16)	signed NArray::INT (wasted memory)	Numo::UInt16
to_na(:GDT_UInt32)	signed NArray::INT (values > 2^31 - 1 overflow)	Numo::UInt32
to_na(:GDT_Float32)	double (NArray::FLOAT aliases DFLOAT)	true single precision (Numo::SFloat)
to_na(:GDT_CFloat32)	double complex	Numo::SComplex
RasterBand#to_nna	Numo::NArray[*rows] -- Ruby integers infer Int32	alias of #to_na, honors band data type
RasterBand#projected_points	indexed [coord, x, y], nested [line][pixel][coord]	same indexing, nested [coord][pixel][line] (doc updated)
Dataset#to_na	band-major [band][x][y] nesting, NMatrix upcast byte to int	Numo::NArray.dstack: per-pixel tuples [y, x, band], dtype preserved
Grid#create points	Array or NArray	Array or Numo::NArray
GDAL._narray_from_data_type() (no size)	empty shapeless NArray	[0]-shaped array

Type-mapping is now exact:

def _gdal_data_type_to_numo_narray_type_constant(data_type)
  case data_type
  when :GDT_Byte                               then Numo::UInt8
  when :GDT_Int16                              then Numo::Int16
  when :GDT_UInt16                             then Numo::UInt16
  when :GDT_Int32                              then Numo::Int32
  when :GDT_UInt32                             then Numo::UInt32
  when :GDT_Float32                            then Numo::SFloat
  when :GDT_Float64                            then Numo::DFloat
  when :GDT_CInt16, :GDT_CInt32, :GDT_CFloat32 then Numo::SComplex
  when :GDT_CFloat64                           then Numo::DComplex
  else
    raise GDAL::InvalidDataType, "Unknown data type: #{data_type}"
  end
end

Notes for reviewers

• Dataset#to_na had no coverage and its previous doc example promised output no implementation ever produced; it now has specs and honest docs (see test(gdal): pin Dataset#to_na NArray behavior #151 for the archaeology).
• projected_points still truncates coordinates on integer bands (pre-existing; faithful port). A follow-up PR will switch coordinate storage to Numo::DFloat.
• Known migration note for consumers: code iterating Dataset#to_na.to_a or projected_points.to_a must swap loop nesting; code using indexed access ([y, x, band] / [coord, x, y]) is unaffected.

Why Dataset#to_na changes shape here, and what is deliberately NOT changed

This PR's goal is a gem swap that keeps behavior as-is wherever numo permits. Dataset#to_na is the one place a behavior-identical port is impossible:

• The old implementation depended on NMatrix, which is removed together with narray, so the method had to be rewritten either way (see test(gdal): pin Dataset#to_na NArray behavior #151 for the archaeology: the transpose was a 2014 zip-bands-into-pixels idiom that never actually produced its documented per-pixel output on real 2-D bands).
• narray and numo disagree on one convention (narray declares dimensions fastest-first, numo fastest-last), so for any 3-D result you can preserve either the indexed access or the nested #to_a representation -- never both.
• This port preserves indexed access exactly: result[y, x, band] returns the same element before and after (the pinned "is indexed as [y, x, band]" spec passes unchanged on both sides). The nested representation changing from band-major [band][x][y] to per-pixel [y][x][band] tuples is the forced consequence -- which happens to be what the 2014 doc example always promised.

Any further semantic redesign -- ordering guarantees, a different stacking layout, the projected_points coordinate typing/nesting -- is deliberately out of scope and deferred to separate follow-up PRs, so this one stays reviewable as "same behavior, new backing gem, honest specs".

Put concretely for Dataset#to_na consumers: reading one pixel's band values -- result[y, x, true] -- worked before this PR (the old index order accidentally fulfilled the documented "points per pixel" intent) and works identically after it; the pinned spec example for it passes unchanged on both sides of the stack. What this PR changes is only the nested representation: #to_a/iteration used to show band-major [band][x][y] planes and now shows the same per-pixel tuples the indexed access always gave, so the two views of the data finally agree with each other and with the docs.

[Oleksii Leonov (oleksii-leonov)]

Issue #55.

[Steve Loveless (turboladen)]

👍

[Steve Loveless (turboladen)]

Just a note for any future 👀 that this contains API-breaking changes, so should cause a major version bump.

[Kurt Ronshausen (kurtronshausen)]

Just a note for any future 👀 that this contains API-breaking changes, so should cause a major version bump.

Isn't the convention usually to have the maintainers (us) bump the version?

[Steve Loveless (turboladen)]

Just a note for any future 👀 that this contains API-breaking changes, so should cause a major version bump.

Isn't the convention usually to have the maintainers (us) bump the version?

Yeah. But just wanted to call this out.

[Steve Loveless (turboladen)]

Oleksii Leonov (@oleksii-leonov) could you rebase and we'll get this merged?

[Copilot]

Pull request overview

This PR completes the migration from the discontinued narray gem to numo-narray, updating internal helpers and raster APIs to construct/return Numo::NArray instances with more precise GDAL-to-array type mappings (notably for UInt16/UInt32), and removing the old narray dependency and monkeypatch.

Changes:

• Replace narray requires/usages with numo-narray across GDAL/OGR extension points.
• Update GDAL data type → array type mapping to use Numo::* classes with improved precision for unsigned integer types.
• Update unit specs to reflect numo-narray behavior and APIs.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
spec/unit/gdal/internal_helpers_spec.rb	Updates expectations to Numo::* types and Numo::NArray allocation semantics.
spec/unit/gdal/extensions/raster_band/io_extensions_spec.rb	Adjusts raster-band IO expectations for Numo::NArray indexing/serialization.
spec/unit/gdal/extensions/raster_band/extensions_spec.rb	Updates RasterBand#to_na expectations to Numo::* typed arrays.
spec/unit/gdal/extensions/raster_band_classifier_spec.rb	Updates classifier setup away from indgen! for numo-narray.
lib/ogr/coordinate_transformation.rb	Removes narray require (no longer needed).
lib/gdal/raster_band.rb	Removes narray require (migration cleanup).
lib/gdal/internal_helpers.rb	Introduces numo-narray type mapping and deprecates legacy NArray mapping helpers.
lib/gdal/grid.rb	Switches to numo/narray and updates type checks/docs.
lib/gdal/extensions/raster_band/extensions.rb	Makes to_na/to_nna return Numo::NArray and updates projected-points allocation.
lib/gdal/extensions/gridder.rb	Removes narray require (migration cleanup).
lib/gdal/extensions/dataset/extensions.rb	Switches dataset-level to_na to build Numo::NArray output.
lib/ffi-gdal.rb	Removes ext/narray_ext load.
lib/ext/narray_ext.rb	Deletes legacy NArray#type monkeypatch.
ffi-gdal.gemspec	Drops narray dependency and adds numo-narray.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Randy Stoller (tindron)]

numo-narray hasn't had a release since 2022. numo-narray-alt is a maintained drop in replacement. Should we consider switching?

[Kurt Ronshausen (kurtronshausen)]

numo-narray hasn't had a release since 2022. numo-narray-alt is a maintained drop in replacement. Should we consider switching?

sounds good to me.

[Oleksii Leonov (oleksii-leonov)]

Yes, numo-narray-alt looks like a good solution.
I will rebase the PR and switch to numo-narray-alt.

[Oleksii Leonov (oleksii-leonov)]

Steve Loveless (@turboladen) Randy Stoller (@tindron)

1. There are some changes in behaviour for code that were not covered by the specs previously. I opened a separate specs-only PR test(gdal): pin Dataset#to_na NArray behavior #151 to document the current behaviour for legacy NArray to create a clean baseline. This makes behaviour changes caused by switching to Numo clearly visible and documented in the specs.
2. Let's merge and release the switch to numo-narray first. Then we can switch to numo-narray-alt in a separate PR and release. Currently, users of ffi-gdal may have numo-narray as a dependency in their Gemfiles (used for other purposes). And adding numo-narray-alt may cause conflicts/issue if both numo-narray and numo-narray-alt are present.