help cliplineclipgeo v1.1 (GitHub)

CLIPLINE

clipline implements the Cohen-Sutherland algorithm in Stata. It takes a set of lines,
defined by x1 y1 x2 y2 coordinates and clips its on a bounding box. The
bounding box can be manually defined or automatically generated.

The program is intended to be an intermediate program, to support other programs that require clipping.
For example, it is used in the clipping of infinite rays in Voronoi diagrams, or reducing the extent of spatial data.

Syntax

clipline x1 y1 x2 y2, [box(x_min x_max y_min y_max)] [offset(number)] [lines] [box]

clipline x1 y1 x2 y2 The lines are defined as coordinate pairs (x1,y1) and (x2,y2). These are represented by four numeric variables. Please make the order sequence of the variables is correct.

box(x_min x_max y_min y_max) Manually define the bounding box in the order specified. If no box is set, the minimum and maximum values of the lines are used.

offset(value) Offset defines the how much the box needs to shrink or expand in size. The default value is set at 0 (no change in box size). If we set offset(-0.1) then it implies that bounds on the axes are reduced by delta = (max - min) * 0.1, and the new bounds are, xmin = xmin + xdelta, xmax = xmax - xdelta for the x-axis. Simiarly yxmin = ymin + ydelta, ymax = ymax - ydelta for the y-axis.

lines Export the lines back to Stata as new variables clip_x1, clip_y1, clip_x2, clip_y2. These can be plotted using twoway pcspike.

box Export the coordinates of the box back to Stata as new variables box_x, box_y. The first coordinate is repeated to allow us to draw a complete line. These can be plotted using the twoway line box_y box_x option.

If no options are specified, then nothing is returned. The evaluated clipped lines and box coordinates are stored as Mata matrices that can be recovered later. Type mata mata describe to view them.

Test the code

You can copy the following code in a dofile to run the example:

example do-file content

clear
set obs 100

gen id = _n
gen x1 = runiform(1,50)
gen y1 = runiform(1,50)
gen x2 = runiform(1,50)
gen y2 = runiform(1,50)

clipline x1 y1 x2 y2, offset(-0.2) lines addbox

twoway ///
(pcspike y1 x1 y2 x2, lw(thin) lc(gs12)) ///
(pcspike clip_y1 clip_x1 clip_y2 clip_x2, lw(thin)) ///
(line box_y box_x, lc(black) lw(0.4)) ///
, legend(off)

clipline x1 y1 x2 y2, box(5 35 10 40) lines addbox

twoway ///
(pcspike y1 x1 y2 x2, lw(thin) lc(gs12)) ///
(pcspike clip_y1 clip_x1 clip_y2 clip_x2, lw(thin)) ///
(line box_y box_x, lc(black) lw(0.4)) ///
, legend(off)

Keywords: Stata, graphs, line clipping, Cohen-Sutherland
Version: clipline version 1.1
This release: 02 Apr 2022
First release: 05 Dec 2021
License: MIT

Author: Asjad Naqvi (WU Wien and IIASA, Austria)
E-mail: asjadnaqvi@gmail.com
Twitter: @AsjadNaqvi