GRASS GIS 8 Programmer's Manual  8.4.0dev(2024)-535c39c9fc
line.c File Reference

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:

Go to the source code of this file.

Functions

struct line_pntsVect__new_line_struct (void)
 Creates and initializes a struct line_pnts (internal use only) More...
 
struct line_pntsVect_new_line_struct (void)
 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 (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.

(C) 2001-2009 by the GRASS Development Team

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
Pointspointer to line_pnts structure
x,y,zpoint coordinates to be added
Returns
number of points
-1 on error (out of memory)

Definition at line 148 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
Pointspointer to line_pnts structure
APointspoints to be included
directiondirection (GV_FORWARD, GV_BACKWARD)
Returns
new number of points
-1 on out of memory

Definition at line 335 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
Pointspointer to line_pnts structure
x,y,zcoordinates arrays
nnumber of points
Returns
number of points copied

Definition at line 380 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
Pointspointer to line_ptns structure
x,y,zarray of coordinates
nnumber 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
ppointer 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 ( struct Map_info Map,
int  line,
int  field 
)

Fetches FIRST category number for given vector line and field.

Parameters
Mappointer to Map_info structure
lineline id
fieldlayer number
Returns
-1 no category
category number (>=0)

Definition at line 929 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
Pointspointer to line_pnts structure
Returns
number of points

Definition at line 267 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
Pointspointer to line_pnts structure
[out]Boxbounding box

Definition at line 888 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
Pointspointer to line_pnts structure
indexpoint (from 0 to Points->n_points-1)
Returns
number of points

Definition at line 210 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
pointspointer to line_pnts structure
ux,uy,uzpoint coordinates
with_zflag if to use z coordinate (3D calculation)
[out]px,py,pzpoint on line
[out]distdistance to line
[out]spdistdistance to point on line from segment beginning
[out]lpdistdistance to point on line from line beginning along line
Returns
nearest segment (first is 1)

Definition at line 648 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
pointspointer to line_pnts structure
ux,uy,uzpoint coordinates
with_zflag if to use z coordinate (3D calculation)
[out]px,py,pzpoint on line
[out]distdistance to line
[out]spdistdistance to point on line from segment beginning
[out]lpdistdistance to point on line from line beginning along line
Returns
nearest segment (first is 1)

Definition at line 751 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
Pointspointer to line_pnts structure geometry
Returns
line length

Definition at line 602 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
Pointspointer to line_pnts structure
indexpoint index (from 0 to Points->n_points-1)
xpointer to x coordinate or NULL
ypointer to y coordinate or NULL
zpointer to z coordinate or NULL
Returns
number of points

Definition at line 244 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
Pointspointer to line_pnts structure
index(from 0 to Points->n_points-1)
x,y,zpoint coordinates
Returns
number of points
-1 on error (allocation)

Definition at line 176 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
Pointspointer to line_pnts structure geometry
Returns
line length

Definition at line 575 of file line.c.

◆ Vect_line_prune()

int Vect_line_prune ( struct line_pnts Points)

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

Parameters
Pointspointer to line_pnts structure
Returns
number of points

Definition at line 279 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
Pointspointer to line_pnts structure
thresholdthreshold value
Returns
number of points in result

Definition at line 309 of file line.c.

◆ Vect_line_reverse()

void Vect_line_reverse ( struct line_pnts Points)

Reverse the order of vertices.

Parameters
Pointspointer to line_pnts structure to be changed

Definition at line 898 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
InPointsinput line
startsegment number
endsegment number
OutPointsoutput line
Returns
1 success
0 error when start > length or end < 0 or start < 0 or end > length

Definition at line 517 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_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
Pointspointer to line_pnts structure
distancedistance value
x,y,zpointers to point coordinates or NULL
anglepointer to angle of line in that point (radians, counter clockwise from x axis) or NULL
slopepointer 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 413 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,z1first point
x2,y2,z2second point
with_zuse z coordinate
Returns
distance

Definition at line 866 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
Pointspointer to line_pnts structure to be reset

Definition at line 129 of file line.c.

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