# Metview Macro

# **************************** LICENSE START ***********************************
#
# Copyright 2013 ECMWF. This software is distributed under the terms
# of the Apache License version 2.0. In applying this license, ECMWF does not
# waive the privileges and immunities granted to it by virtue of its status as
# an Intergovernmental Organization or submit itself to any jurisdiction.
#
# ***************************** LICENSE END ************************************

# **************************************************************************
# Function      : mvl_geoline
#
# Syntax        : definition mvl_geoline ( lat1 : number, lon1 : number,
#                                          lat2 : number, lon2 : number,  incrm : number)
#
# Category      : VISUAL
#
# OneLineDesc   : Returns a line marking a line of interest
#
# Description   : Returns a visual definintion for drawing a line to mark
#                 a geographical line of interest. This line is projection-independent.
#
# Parameters    : lat1,lon1,lat2,lon2 - coordinates of the two end-points of the line lat/long.
#                 incrm     - the increments in which the line is drawn (degrees)
#                             (not relevant for cylindrical projection)
#
# Return Value  : an Input Visualiser that may be used in a plot() command
#
# Example Usage : 
#
#                   lat1  = 60
#                   lon1  = -130
#                   lat2  = 30
#                   lon2  = -100
#                   incrm = 1
#
#                   my_line = mvl_geoline(lat1,lon1,lat2,lon2, incrm)
#
#                   plot ( display_window, data, my_line, mgraph())
#
# **************************************************************************

function mvl_geoline (lat1 : number, lon1 : number,
                      lat2 : number, lon2 : number, incrm : number)
                 
    dx = lon2 - lon1
    dy = lat2 - lat1

    if abs(dx) > abs(dy) then
        incr_lon = 1  # increment along longitudes
        if lon1 > lon2 then
            incrm = -incrm
        end if
    else
        incr_lon = 0  # increment along latitudes
        if lat1 > lat2 then
            incrm = -incrm
        end if
    end if


	# calculate the line equation

    xcoord = nil
    ycoord = nil

	if dx = 0 then  # vertical line
    	for y = lat1 to lat2 by incrm do
    		ycoord = ycoord & [y]
    		xcoord = xcoord & [lon1]
    	end for

    	# make sure the last point is included
    	ycoord = ycoord & [lat2]
    	xcoord = xcoord & [lon2]

	else # more general case - not a vertical line

	   a = (lat1 - lat2) / (lon1 - lon2)
	   b = lat1 - a*lon1

        if incr_lon then
        	for x = lon1 to lon2 by incrm do
        		xcoord = xcoord & [x]
        		ycoord = ycoord & [a*x + b]
        	end for

        	# make sure the last point is included
        	xcoord = xcoord & [lon2]
        	ycoord = ycoord & [a*lon2 + b]
        else
        	for y = lat1 to lat2 by incrm do
        		ycoord = ycoord & [y]
        		xcoord = xcoord & [(y-b)/a]
        	end for

        	# make sure the last point is included
        	ycoord = ycoord & [lat2]
        	xcoord = xcoord & [(lat2-b)/a]
        end if

    end if

	# set up a curve with suitable vis def
    geoline_curve = input_visualiser
    (
        input_plot_type        :    "geo_points",
        input_longitude_values :    xcoord,
        input_latitude_values  :    ycoord,
        input_values           :    ycoord
     )

	return geoline_curve

end mvl_geoline
