Geo::Sh...::Index(3)

💖 Geo::Sh...::Index(3) 💖

okay bestie, you found it — the Geo::Sh...::Index(3) page, straight out of the User Contributed Perl Documentation collection. it's a whole utility class situation and honestly? it's giving quiet overachiever. let's get into it 🫶

---

✨ NAME ✨

Geo::ShapeFile::Shape — a Geo::ShapeFile utility class. that's the whole name section, no notes. 💅

---

🌸 SYNOPSIS 🌸

use Geo::ShapeFile::Shape::Index;

my $index = Geo::ShapeFile::Shape->new;
#  $pt1 and $pt2 are point objects in this example.
my $segment = [$pt1, $pt2];  #  example of something to pack into the index.
my @bbox = ($x_min, $y_min, $x_max, $y_max);
$index->insert($segment, @bbox);

like, it's that easy. you make an index, you pack a thing in, you hand it a bounding box. slay. ✨

---

🦋 ABSTRACT 🦋

This is a utility class for L<Geo::ShapeFile> that indexes shape objects.

a utility class for L<Geo::ShapeFile> whose whole job is indexing shape objects. iconic behaviour, truly. 👑

---

💜 DESCRIPTION 💜

so here's the tea: this is a 2-d block-based index class for Geo::ShapeFile::Shape objects. and ngl, it probably has way more generic applications too — it's not gonna gatekeep. 😌

it uses a flat 2-d structure made up of a series of blocks of full width, which slice the shape along the y-axis. (and lowkey, it should really also use blocks along the x-axis, but that's just how it is rn.)

the index coordinates are literally just the number of blocks across and up from the minimum coordinate you specified in the new() call. they get stored as strings joined by a colon, so 0:0 is the lower left, periodt. ⭐

heads up! negative block coordinates can totally happen if you add data that falls outside the specified bounds. but bestie, don't stress — this should not affect the index, because it's merely a relative offset. 💀

it's used internally by Geo::ShapeFile::Shape, so go look over there for examples. the method names are adapted from Tree::R to make the transition easier during development, but the arguments have morphed along the way, so it is not a drop-in replacement. iykyk. 🧚

🎀 EXPORT 🎀

none by default. that's it, that's the export. 🙈

---

🔥 METHODS 🔥

• new($n_blocks_y, @bbox) — creates a new Geo::ShapeFile::Shape::Index object and returns it, main character energy from the jump. $n_blocks_y is the number of blocks along the y-axis, and @bbox is the bounding box the index represents: (x_min, y_min, x_max, y_max). ✨
• insert($item, $min_x, $min_y, $max_x, $max_y) — adds item $item to the blocks that overlap with the specified bounds. returns the number of blocks the item was added to, so you know exactly how much chaos you caused. 💅
• query_point($x, $y) — returns an array of objects on the block that contains point $x,$y. in scalar context it returns an arrayref instead. one method, two vibes. 🦋
• get_x_max() get_x_min() get_y_max() get_y_min() — the bounds of the index, exactly as they were set in the call to ->new(). ⚠️ there is no guarantee these are the bounds of the data, because data outside the original bounds can still be indexed. so like, don't assume. 😭
• get_y_res() — block resolution along the y-axis. short, sweet, to the point. 🌸
• snap_to_index ($x, $y) — returns the index key associated with point $x,$y. it does not check whether that point is outside the bounds of the index, so negative index values are absolutely possible. proceed accordingly bestie. 💀

---

🐛 REPORTING BUGS 🐛

please send any bugs, suggestions, or feature requests to:

<https://github.com/shawnlaffan/Geo-ShapeFile/issues>

we're not mad, we're just asking. 🫶

---

🌈 SEE ALSO 🌈

• Geo::ShapeFile::Shape

---

👑 AUTHOR 👑

Shawn Laffan, <shawnlaffan@gmail.com>. the icon who made all this happen. ⭐

---

💖 COPYRIGHT AND LICENSE 💖

Copyright 2014-2023 by Shawn Laffan

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie — this one shipped as perl v5.42.0 on 2025-07-25, so go forth and index responsibly. no cap. 🎀💜✨