feat(rust/sedona-raster): add ViewEntries view-spec module

[james-willis]

This PR isolates just the machinery for the lazy view support. A subsequent PR will contain the integration(s) into the raster type.

This is spun out from #813

AI generated description

Adds view_entries.rs, the per-axis view-spec layer for N-D raster bands. No consumers are wired up yet — the reader/builder integration is the follow-up — so there is no behavior change.

ViewEntry

The per-axis spec (source_axis, start, step, steps), moved here from traits.rs and re-exported as crate::traits::ViewEntry so existing import paths are unchanged. step == 0 is broadcast, negative step is reverse iteration, and steps == 0 is an empty axis.

ViewEntries

A newtype over Vec<ViewEntry> that owns the view logic:

• validate(source_shape) — the load-bearing check: view length matches source_shape, each source_axis is in range and the axes form a permutation of 0..ndim, steps >= 0, and the addressed extent start + (steps - 1) * step stays within [0, source_shape[axis]). Uses checked_* arithmetic so a pathological spec errors rather than wrapping.
• visible_shape() — the visible extent (steps per axis); this is what a band reports as its shape().
• is_identity(source_shape) — whether the view is the canonical no-op, so it can be stored as a NULL view row.
• compose(next) — stacks a new view over an already-viewed band, translating next's axes (which index the visible axes) back onto the source axes. This is what lets views nest without materializing.
• identity_for_shape, plus len / is_empty / as_slice / iter accessors.

view_entries! macro

A terse constructor taking start:stop half-open ranges per axis: view_entries![0:4, 1:5] yields source_axis = position, step = 1, steps = stop - start for each axis. Convenience for call sites and tests.

Scope

Pure spec logic — no I/O, no Arrow columns; the only allocation is the small Vec<ViewEntry> (ndim is a handful). Fully unit-tested in-module (validation rejections, composition, identity, visible-shape). It's the substrate the integration PR builds on.

[paleolimbot]

Thank you!

I am still a tiny bit confused as to why source_axis is part of the view entry, since it seems there's a bit of work spent validating it only appears once. Can it be dropped and the index of the ViewEntry in the Vec be used instead? (Or if not, can a comment get added explaining why that can't happen?)

[james-willis]

I am still a tiny bit confused as to why source_axis is part of the view entry

One functionality of this views feature is to allow bands to be permuted, e.g. [x, y, z] -> [z, y, x]. The indices of the entries in ViewEntries defines the target band ordering. the values of source_axis defines the source band location.

The index cannot be used to define the source axis because it is used to define the target axis.

One example: GDAL-backed functions with band stacking require y then x are the last two dimensions. If the source raster does not have this behavior a permutation is neccessary.

[paleolimbot]

Got it...this is also defining the permutation in addition to the view.