Geo::Sh...e::Shape(3)

📦
version 3.03 · 2 versions
, in fedora 43

💖 Geo::ShapeFile::Shape — the vibe-coded field guide 💖

So bestie, you found the manual page for Geo::ShapeFile::Shape, from the User Contributed Perl Documentation collection. It's a lil' utility class. It's giving backstage pass. It's not the main character, but it holds the shape data, so honestly? Iconic.

✨ NAME ✨

Geo::ShapeFile::Shape — the Geo::ShapeFile utility class. 🎀

🌸 SYNOPSIS 🌸

use Geo::ShapeFile::Shape;

my $shape = Geo::ShapeFile::Shape->new;
$shape->parse_shp($shape_data);

That's it. That's the whole entrance. 🦋

🧚 ABSTRACT 🧚

It's a utility class for Geo::ShapeFile that represents shapes. Simple as. 💅

💜 DESCRIPTION 💜

Okay so this is the Geo::ShapeFile utility class that actually contains the shape data for one individual shape from the shp file. One shape. Its own little world. Its own little data. 🫶

🍓 EXPORT 🍓

None by default. Nope, zero, nada, don't come looking for exports here. 🙈

👑 METHODS 👑

new()

Creates a new Geo::ShapeFile::Shape object. Takes no arguments, returns the shiny new object. ✨

Normally Geo::ShapeFile does this for you when you call its get_shp_record() method, so like, you shouldn't need to create a new object yourself. (Eventually this module will have support for creating shapefiles rather than just reading them, and then this method will become important.) Future plans, bestie. 🔮

num_parts()

Returns the number of parts that make up this shape. 🔢

num_points()

Returns the number of points that make up this shape. 🔢

points()

Returns an array of Geo::ShapeFile::Point objects containing all the points in this shape. 🎯

Heads up though: a shape can contain multiple segments, and those segments may not be directly connected. So you probably don't wanna use this to grab points you're about to plot. If you're drawing the shape, you want get_part() to pull the individual parts instead. fr fr, listen to this one. 😭

get_part($part_index);

Returns the specified part of the shape. This is the info you want if you intend to draw the shape. 💅

You can iterate through all the parts that make up a shape like this:

for(1 .. $obj->num_parts) {
  my $part = $obj->get_part($_);
  # ... do something here, draw a map maybe
}

Draw the map. You know you want to. 🗺️✨

shape_type()

Returns the numeric type of this shape. Use Geo::ShapeFile::type() to turn that number into the human-readable name. 🔤

shape_id()

Returns the id number for this shape, as contained in the shp file. 🆔

x_min() x_max() y_min() y_max() z_min() z_max() m_min() m_max()

Returns the minimum/maximum ranges of the X, Y, Z, or M values for this shape, as contained in its header information. 📐

has_point($point)

Returns true if the point object provided matches one of the points in the shape. ✅

Note that this does a simple comparison with the points that make up the shape — it will not find a point that falls along a vertex between two points in the shape. Also, see the Geo::ShapeFile::Point documentation for a note about how to exclude Z and/or M data from being considered when matching points. 🙈

contains_point($point); =item contains_point($point, $use_index);

Returns true if the specified point falls in the interior of this shape, and false if the point is outside the shape. 🎯

Return value is unspecified if the point is one of the vertices or lies on some segment of the bounding polygon. So like... don't @ us on that one. 😭

Passing $use_index uses a spatial index if defined (building it if needed). See build_spatial_index for more details. This will be the default behaviour in a future release. 🔮

Note that the algorithm uses a sidedness algorithm ignoring Z and M fields, and so will likely not work if the point is contained within a shape winding the wrong way. Polygon shapes should be anticlockwise for outer boundaries, and clockwise for inner void polygons. Periodt. 💅

build_spatial_index ($index_res)

Builds a spatial index for use in contains_point(). 🏗️

$index_res is a positive integer which sets the nnumber of along the y-axis. A value of 0 lets the system determine the number. 🧮

get_spatial_index()

Gets the spatial index. It's a hash indexed by part number. Returns a hash reference in scalar context. 📇

bounds

Returns the object's bounds as an array (x_min, y_min, x_max, y_max). Returns an array ref in scalar context. 📦

get_segments($part)

Returns an array consisting of array hashes, which contain the points for each segment of a multi-segment part. 🧩

vertex_centroid( $part );

Returns a Geo::ShapeFile::Point that represents the calculated centroid of the shape's vertices. If given a part index, calculates just for that part; otherwise calculates it for the entire shape. See "centroid" for more on vertex_centroid vs area_centroid. 🎯

area_centroid( $part );

Returns a Geo::ShapeFile::Point that represents the calculated area centroid of the shape. If given a part index, calculates just for that part; otherwise calculates it for the entire shape. See "centroid" for more on vertex_centroid vs area_centroid. 🎯

centroid($part)

For backwards-compatibility reasons, centroid() is currently an alias to vertex_centroid(), although it would probably make more sense for it to point to area_centroid().

To avoid confusion (and possible future deprecation), you should avoid this and use either vertex_centroid or area_centroid. Bestie, just pick one of the real ones, okay? 😭

dump()

Returns a text dump of the object, showing:

  • the shape type
  • the id number
  • the number of parts
  • the number of total points
  • the bounds for the X, Y, Z, and M ranges
  • the coordinates of the points in each part of the shape

Full reveal. No secrets. 💅✨

😭 REPORTING BUGS 😭

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

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

They want to hear from you, fr fr. 🫶

🦋 SEE ALSO 🦋

  • Geo::ShapeFile

🌈 AUTHOR 🌈

  • Jason Kohles, <email@jasonkohles.com>
  • Shawn Laffan, <shawnlaffan@gmail.com>

Legends, both of them. 👑

Copyright 2002-2013 by Jason Kohles

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. 🌸

Okay that's the whole page bestie, no cap, every last flag and method accounted for. 💖 This one's running on perl v5.42.0, dated 2025-07-25, and it's the Geo::Sh...e::Shape(3) page from the User Contributed Perl Documentation. Slay, go read some shapes. ✨🦋💅

📦 where this page comes from