Vector library - vector feature geometry. More...

#include <stdlib.h>
#include <math.h>
#include <grass/vector.h>
#include <grass/glocale.h>

Include dependency graph for line.c:

Functions
struct line_pnts *	Vect__new_line_struct (void)
	Creates and initializes a struct line_pnts (internal use only) More...

struct line_pnts *	Vect_new_line_struct ()
	Creates and initializes a line_pnts structure. More...

void	Vect_destroy_line_struct (struct line_pnts *p)
	Frees all memory associated with a line_pnts structure, including the structure itself. More...

int	Vect_copy_xyz_to_pnts (struct line_pnts Points, const double x, const double y, const double z, int n)
	Copy points from array to line_pnts structure. More...

void	Vect_reset_line (struct line_pnts *Points)
	Reset line. More...

int	Vect_append_point (struct line_pnts *Points, double x, double y, double z)
	Appends one point to the end of a line. More...

int	Vect_line_insert_point (struct line_pnts *Points, int index, double x, double y, double z)
	Insert new point at index position and move all old points at that position and above up. More...

int	Vect_line_delete_point (struct line_pnts *Points, int index)
	Delete point at given index and move all points above down. More...

int	Vect_line_get_point (const struct line_pnts Points, int index, double x, double y, double z)
	Get line point of given index. More...

int	Vect_get_num_line_points (const struct line_pnts *Points)
	Get number of line points. More...

int	Vect_line_prune (struct line_pnts *Points)
	Remove duplicate points, i.e. zero length segments. More...

int	Vect_line_prune_thresh (struct line_pnts *Points, double threshold)
	Remove points in threshold. More...

int	Vect_append_points (struct line_pnts Points, const struct line_pnts APoints, int direction)
	Appends points to the end of a line. More...

int	Vect_copy_pnts_to_xyz (const struct line_pnts Points, double x, double y, double z, int *n)
	Copy points from line structure to array. More...

int	Vect_point_on_line (const struct line_pnts Points, double distance, double x, double y, double z, double angle, double slope)
	Find point on line in the specified distance. More...

int	Vect_line_segment (const struct line_pnts InPoints, double start, double end, struct line_pnts OutPoints)
	Create line segment. More...

double	Vect_line_length (const struct line_pnts *Points)
	Calculate line length, 3D-length in case of 3D vector line. More...

double	Vect_line_geodesic_length (const struct line_pnts *Points)
	Calculate line length. More...

int	Vect_line_distance (const struct line_pnts points, double ux, double uy, double uz, int with_z, double px, double py, double pz, double dist, double spdist, double *lpdist)
	Calculate distance of point to line. More...

int	Vect_line_geodesic_distance (const struct line_pnts points, double ux, double uy, double uz, int with_z, double px, double py, double pz, double dist, double spdist, double *lpdist)
	Calculate geodesic distance of point to line in meters. More...

double	Vect_points_distance (double x1, double y1, double z1, double x2, double y2, double z2, int with_z)
	Calculate distance of 2 points. More...

void	Vect_line_box (const struct line_pnts Points, struct bound_box Box)
	Get bounding box of line. More...

void	Vect_line_reverse (struct line_pnts *Points)
	Reverse the order of vertices. More...

int	Vect_get_line_cat (const struct Map_info *Map, int line, int field)
	Fetches FIRST category number for given vector line and field. More...

Detailed Description

Vector library - vector feature geometry.

This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

Author: Original author CERL, probably Dave Gerdes or Mike Higgins.; Update to GRASS 5.7 Radim Blazek and David D. Gray.; Some updates for GRASS 7 by Martin Landa <landa.martin gmail.com>

Definition in file line.c.

Function Documentation

◆ Vect__new_line_struct()

struct line_pnts * Vect__new_line_struct ( void )

Creates and initializes a struct line_pnts (internal use only)

Use Vect_new_line_struct() instead.

Returns: pointer to allocated line_pnts structure; NULL on error

Definition at line 55 of file line.c.

References line_pnts::alloc_points, malloc(), line_pnts::n_points, NULL, line_pnts::x, line_pnts::y, and line_pnts::z.

Referenced by Vect_new_line_struct().

◆ Vect_append_point()

int Vect_append_point	(	struct line_pnts *	Points,
		double	x,
		double	y,
		double	z
	)

Appends one point to the end of a line.

If you are re-using a line struct, be sure to clear out old data first by calling Vect_reset_line().

Calls G_fatal_error() when out of memory.

Parameters

Points	pointer to line_pnts structure
x,y,z	point coordinates to be added

Returns: number of points; -1 on error (out of memory)

Definition at line 149 of file line.c.

◆ Vect_append_points()

int Vect_append_points	(	struct line_pnts *	Points,
		const struct line_pnts *	APoints,
		int	direction
	)

Appends points to the end of a line.

Note, this will append to whatever is in line_pnts structure. If you are re-using a line struct, be sure to clear out old data first by calling Vect_reset_line().

Parameters

Points	pointer to line_pnts structure
APoints	points to be included
direction	direction (GV_FORWARD, GV_BACKWARD)

Returns: new number of points; -1 on out of memory

Definition at line 337 of file line.c.

◆ Vect_copy_pnts_to_xyz()

int Vect_copy_pnts_to_xyz	(	const struct line_pnts *	Points,
		double *	x,
		double *	y,
		double *	z,
		int *	n
	)

Copy points from line structure to array.

x/y/z arrays MUST be at least as large as Points->n_points

Also note that n is a pointer to int.

Parameters

Points	pointer to line_pnts structure
x,y,z	coordinates arrays
n	number of points

Returns: number of points copied

Definition at line 383 of file line.c.

◆ Vect_copy_xyz_to_pnts()

int Vect_copy_xyz_to_pnts	(	struct line_pnts *	Points,
		const double *	x,
		const double *	y,
		const double *	z,
		int	n
	)

Copy points from array to line_pnts structure.

Parameters

Points	pointer to line_ptns structure
x,y,z	array of coordinates
n	number of points to be copied

Returns: 0 on success; -1 on out of memory

Definition at line 99 of file line.c.

◆ Vect_destroy_line_struct()

void Vect_destroy_line_struct ( struct line_pnts * p )

Frees all memory associated with a line_pnts structure, including the structure itself.

Parameters

p	pointer to line_pnts structure

Definition at line 77 of file line.c.

References line_pnts::alloc_points, G_free(), line_pnts::x, line_pnts::y, and line_pnts::z.

Referenced by Vect__free_cache(), and vector2perimeters().

◆ Vect_get_line_cat()

int Vect_get_line_cat	(	const struct Map_info *	Map,
		int	line,
		int	field
	)

Fetches FIRST category number for given vector line and field.

Parameters

Map	pointer to Map_info structure
line	line id
field	layer number

Returns: -1 no category; category number (>=0)

Definition at line 963 of file line.c.

◆ Vect_get_num_line_points()

int Vect_get_num_line_points ( const struct line_pnts * Points )

Get number of line points.

Parameters

Points pointer to line_pnts structure

Returns: number of points

Definition at line 269 of file line.c.

◆ Vect_line_box()

void Vect_line_box	(	const struct line_pnts *	Points,
		struct bound_box *	Box
	)

Get bounding box of line.

Parameters

	Points	pointer to line_pnts structure
[out]	Box	bounding box

Definition at line 922 of file line.c.

◆ Vect_line_delete_point()

int Vect_line_delete_point	(	struct line_pnts *	Points,
		int	index
	)

Delete point at given index and move all points above down.

Parameters

Points	pointer to line_pnts structure
index	point (from 0 to Points->n_points-1)

Returns: number of points

Definition at line 211 of file line.c.

◆ Vect_line_distance()

int Vect_line_distance	(	const struct line_pnts *	points,
		double	ux,
		double	uy,
		double	uz,
		int	with_z,
		double *	px,
		double *	py,
		double *	pz,
		double *	dist,
		double *	spdist,
		double *	lpdist
	)

Calculate distance of point to line.

Sets (if not null):

px, py - point on line,
dist - distance to line,
spdist - distance to point on line from segment beginning,
lpdist - distance to point on line from line beginning along line

Parameters

	points	pointer to line_pnts structure
	ux,uy,uz	point coordinates
	with_z	flag if to use z coordinate (3D calculation)
[out]	px,py,pz	point on line
[out]	dist	distance to line
[out]	spdist	distance to point on line from segment beginning
[out]	lpdist	distance to point on line from line beginning along line

Returns: nearest segment (first is 1)

Definition at line 651 of file line.c.

References dig_distance2_point_to_line(), line_pnts::n_points, NULL, line_pnts::x, line_pnts::y, and line_pnts::z.

◆ Vect_line_geodesic_distance()

int Vect_line_geodesic_distance	(	const struct line_pnts *	points,
		double	ux,
		double	uy,
		double	uz,
		int	with_z,
		double *	px,
		double *	py,
		double *	pz,
		double *	dist,
		double *	spdist,
		double *	lpdist
	)

Calculate geodesic distance of point to line in meters.

Sets (if not null):

px, py - point on line,
dist - distance to line,
spdist - distance to point on line from segment beginning,
lpdist - distance to point on line from line beginning along line

Parameters

	points	pointer to line_pnts structure
	ux,uy,uz	point coordinates
	with_z	flag if to use z coordinate (3D calculation)
[out]	px,py,pz	point on line
[out]	dist	distance to line
[out]	spdist	distance to point on line from segment beginning
[out]	lpdist	distance to point on line from line beginning along line

Returns: nearest segment (first is 1)

Definition at line 772 of file line.c.

References dig_distance2_point_to_line(), G_begin_distance_calculations(), G_distance(), line_pnts::n_points, NULL, line_pnts::x, line_pnts::y, and line_pnts::z.

◆ Vect_line_geodesic_length()

double Vect_line_geodesic_length ( const struct line_pnts * Points )

Calculate line length.

If projection is LL, the length is measured along the geodesic.

Parameters

Points pointer to line_pnts structure geometry

Returns: line length

Definition at line 604 of file line.c.

◆ Vect_line_get_point()

int Vect_line_get_point	(	const struct line_pnts *	Points,
		int	index,
		double *	x,
		double *	y,
		double *	z
	)

Get line point of given index.

Calls G_fatal_error() when index is not range in.

Parameters

Points	pointer to line_pnts structure
index	point index (from 0 to Points->n_points-1)
x	pointer to x coordinate or NULL
y	pointer to y coordinate or NULL
z	pointer to z coordinate or NULL

Returns: number of points

Definition at line 245 of file line.c.

◆ Vect_line_insert_point()

int Vect_line_insert_point	(	struct line_pnts *	Points,
		int	index,
		double	x,
		double	y,
		double	z
	)

Insert new point at index position and move all old points at that position and above up.

Parameters

Points	pointer to line_pnts structure
index	(from 0 to Points->n_points-1)
x,y,z	point coordinates

Returns: number of points; -1 on error (alocation)

Definition at line 177 of file line.c.

◆ Vect_line_length()

double Vect_line_length ( const struct line_pnts * Points )

Calculate line length, 3D-length in case of 3D vector line.

For Lat-Long use Vect_line_geodesic_length() instead.

Parameters

Points pointer to line_pnts structure geometry

Returns: line length

Definition at line 576 of file line.c.

◆ Vect_line_prune()

int Vect_line_prune ( struct line_pnts * Points )

Remove duplicate points, i.e. zero length segments.

Parameters

Points pointer to line_pnts structure

Returns: number of points

Definition at line 281 of file line.c.

Referenced by Vect_build_line_area().

◆ Vect_line_prune_thresh()

int Vect_line_prune_thresh	(	struct line_pnts *	Points,
		double	threshold
	)

Remove points in threshold.

Parameters

Points	pointer to line_pnts structure
threshold	threshold value

Returns: number of points in result

Definition at line 311 of file line.c.

◆ Vect_line_reverse()

void Vect_line_reverse ( struct line_pnts * Points )

Reverse the order of vertices.

Parameters

Points pointer to line_pnts structure to be changed

Definition at line 932 of file line.c.

◆ Vect_line_segment()

int Vect_line_segment	(	const struct line_pnts *	InPoints,
		double	start,
		double	end,
		struct line_pnts *	OutPoints
	)

Create line segment.

Creates segment of InPoints from start to end measured along the line and write it to OutPoints.

If the distance is greater than line length or negative, error is returned.

Parameters

InPoints	input line
start	segment number
end	segment number
OutPoints	output line

Returns: 1 success; 0 error when start > length or end < 0 or start < 0 or end > length

Definition at line 518 of file line.c.

◆ Vect_new_line_struct()

struct line_pnts* Vect_new_line_struct ( void )

Creates and initializes a line_pnts structure.

This structure is used for reading and writing vector lines and polygons. The library routines handle all memory allocation. If 3 lines in memory are needed at the same time, then simply 3 line_pnts structures have to be used.

To free allocated memory call Vect_destroy_line_struct().

Calls G_fatal_error() on error.

Returns: pointer to line_pnts

Definition at line 45 of file line.c.

References _, G_fatal_error(), NULL, and Vect__new_line_struct().

Referenced by Vect__reallocate_cache(), Vect_build_line_area(), Vect_get_point_in_poly_isl(), Vect_point_buffer2(), and vector2perimeters().

◆ Vect_point_on_line()

int Vect_point_on_line	(	const struct line_pnts *	Points,
		double	distance,
		double *	x,
		double *	y,
		double *	z,
		double *	angle,
		double *	slope
	)

Find point on line in the specified distance.

From the beginning, measured along line.

If the distance is greater than line length or negative, error is returned.

Parameters

Points	pointer to line_pnts structure
distance	distance value
x,y,z	pointers to point coordinates or NULL
angle	pointer to angle of line in that point (radians, counter clockwise from x axis) or NULL
slope	pointer to slope angle in radians (positive up)

Returns: number of segment the point is on (first is 1),; 0 error when point is outside the line

Definition at line 415 of file line.c.

◆ Vect_points_distance()

double Vect_points_distance	(	double	x1,
		double	y1,
		double	z1,
		double	x2,
		double	y2,
		double	z2,
		int	with_z
	)

Calculate distance of 2 points.

Simply uses Pythagoras.

Parameters

x1,y1,z1	first point
x2,y2,z2	second point
with_z	use z coordinate

Returns: distance

Definition at line 898 of file line.c.

Referenced by Vect_find_node(), and Vedit_get_min_distance().

◆ Vect_reset_line()

void Vect_reset_line ( struct line_pnts * Points )

Reset line.

Make sure line structure is clean to be re-used, i.e. it has no points associated with it Points must have previously been created with Vect_new_line_struct().

Parameters

Points pointer to line_pnts structure to be reset

Definition at line 130 of file line.c.

Referenced by Vect__get_area_points_pg(), Vect_get_area_points(), and Vect_get_isle_points().

Functions

Detailed Description

Function Documentation

◆ Vect__new_line_struct()

◆ Vect_append_point()

◆ Vect_append_points()

◆ Vect_copy_pnts_to_xyz()

◆ Vect_copy_xyz_to_pnts()

◆ Vect_destroy_line_struct()

◆ Vect_get_line_cat()

◆ Vect_get_num_line_points()

◆ Vect_line_box()

◆ Vect_line_delete_point()

◆ Vect_line_distance()

◆ Vect_line_geodesic_distance()

◆ Vect_line_geodesic_length()

◆ Vect_line_get_point()

◆ Vect_line_insert_point()

◆ Vect_line_length()

◆ Vect_line_prune()

◆ Vect_line_prune_thresh()

◆ Vect_line_reverse()

◆ Vect_line_segment()

◆ Vect_new_line_struct()

◆ Vect_point_on_line()

◆ Vect_points_distance()

◆ Vect_reset_line()