!=====================================================================
! NGAR: Areas, A Package that Solves Certain Practical Problems in Topology
!=====================================================================
!
! Areas is one of the more complex utilities to use. It require you to
! write a subroutine or two to define exactly what is supposed to be
! done with specific areas after they are defined. For example, if you
! want to draw lines over a portion of your plot and color other
! portions of your plot, you would probably have to write two routines
! to do this: one to draw the lines in selected areas and one to
! color-fill other areas.
!
! The functional outline below shows how Areas works.
!
! 1. Set parameters (optional)
! NG_ARRSET, NG_ARSET0, NG_ARSET1, NG_ARGET1, and
! NG_AESETI, NG_ARSETR, NG_ARGETI, AZRGETR
!
! 2. NG_ARINAM - Initialize area map
!
! 3. NG_AREDAM - Add edges to area map
!
! 4. NG_ARPRAM - Preprocess area map (optional)
!
! 5. Do one, at least, or more of the following:
!
! a. NG_ARDRLN - Break a polyline into segments, each of which
! lies entirely in a single area, then process
each segment individually
!
! b. NG_ARGTAI - Retrieve area identifiers for areas containing
! a given point
!
! c. NG_ARSCAM - Scan an area map to retrieve each subarea, then
! process each subarea individually
!
! 6. NG_ARDBPA - Debug plot (optional)
!
! Note: CNCARG remove the statement "CALL FRAME" and user should
! "CALL NG_SET( 0.050, 0.950, 0.035, 0.935, 0.0, 1.0, 0.0, 1.0, 1)"
! for co-working with NG_ARDBPA
!
! 7. NG_ARMVAM - Moving an area map (optional)
!
!---------------------------------------
!
! Note: CNCARG adding a "optional dummy subprogram arguments", DBR,
! to following AREAS routines
!
! NG_ARGTAI( IAM, XCD, YCD, IAI, IAG, MAI, NAI, ICF, DBR )
!
! NG_ARDRLN( IAM, XCD, YCD, NCD, XCS, YCS, MCS, IAI, IAG, MAI, LPR, DBR )
!
! NG_ARSCAM( IAM, XCS, YCS, MCS, IAI, IAG, MAI, APR, DBR )
!
! NG_ARPRAM( IAM, IF1, IF2, IF3, DBR )
!
! DBR is a user version of the AREAS routine "ARDBPA". If DBR is
! PRESENT, ARDBPA will be replaced
!
!=====================================================================
!
! SUBROUTINE NG_ARINAM (IAM,LAM)
!
! The routine ARINAM is called to initialize a given area map. It must
! be called prior to any AREDAM call for that area map. Input arguments
! are as follows:
!
! Variables:
!
! INTEGER, INTENT(IN ) :: LAM
! INTEGER, INTENT(INOUT) :: IAM(LAM)
!
! IAM is the integer array in which an area map is to be initialized.
!
! LAM is the length of the array IAM.
!
! On output, elements of IAM have been changed, but LAM is unchanged.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_AREDAM (IAM,XCA,YCA,LCA,IGI,IDL,IDR)
!
! The routine AREDAM allows the caller to add an edge, separating two
! areas from each other, to an existing area map.
!
! Variables:
!
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: LCA
! REAL, INTENT(IN ) :: XCA(ABS(LCA)), YCA(ABS(LCA))
! INTEGER, INTENT(IN ) :: IGI, IDL, IDR
!
! IAM - Iis an integer array (dimensioned as specified by a prior call to
! the routine ARINAM) in which resides the area map to which an edge is
! to be added. The user should make no direct changes in the area map;
! only routines in the package AREAS should be allowed to modify it.
!
! XCA is an array of X coordinates of edge points.
!
! YCA is an array of Y coordinates of edge points.
!
! LCA is the number of edge points defined by XCA and YCA, negated if
! AREDAM is to skip the test that might cause it to provide a boundary
! rectangle.
!
! IGI is the identifier of the group to which this edge belongs.
!
! IDL is the identifier of the area to the left of the new edge, in the
! current user coordinate system.
!
! IDR is the identifier of the area to the right of the new edge, in the
! current user coordinate system.
!
! Upon return from AREDAM, all arguments are unchanged except IAM, which
! contains the augmented area map.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARGTAI (IAM,XCD,YCD,IAI,IAG,MAI,NAI,ICF,DBR)
!
! The routine ARGTAI is called to obtain information about a specific
! point in an existing area map created by calls to ARINAM and AREDAM.
!
! Variables:
!
! INTEGER, INTENT(INOUT) :: IAM(*)
! REAL, INTENT(IN ) :: XCD, YCD
! INTEGER, INTENT(IN ) :: MAI
! INTEGER, INTENT( OUT) :: IAI(MAI), IAG(MAI)
! INTEGER, INTENT( OUT) :: NAI
! INTEGER, INTENT(IN ) :: ICF
!
! OPTIONAL :: DBR
! INTERFACE ! same as ARDBPA
! SUBROUTINE DBR( IAM, IGI, LAB )
! IMPLICIT NONE
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: IGI
! CHARACTER(*), INTENT(IN ) :: LAB
! END SUBROUTINE DBR
! END INTERFACE
!
! IAM is the area-map array.
!
! XCD and YCD are the coordinates, in the current user coordinate
! system, of the point at which information is desired.
!
! The arrays IAG and IAI, each of which is dimensioned MAI, are used to
! return information to the caller. For each I from 1 to NAI, IAI(I)
! will be the area identifier associated with group identifier IAG(I).
!
! ICF is a flag set non-zero to indicate that GETSET should be called
! to get the information necessary to do the mapping from the current
! user coordinate system to the internal coordinate system; if ICF is
! zero, no such calls are done and it is assumed that the information
! saved from a previous call is still correct.
!
! DBR is a user version of the AREAS routine "ARDBPA". ARGTAI invokes
! ARPRAM and pass DBR to doing the debug work, that allows user to use
! larger characters for the area identifiers and/or to omit edge
! segments that are too close to the edge of the plotter frame. If DBR
! is PRESENT, ARDBPA will be replaced
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARDRLN (IAM,XCD,YCD,NCD,XCS,YCS,MCS,IAI,IAG,MAI,LPR,DBR)
!
! The routine ARDRLN allows the caller to draw a polyline across the
! area represented by an area map. The polyline is broken into pieces
! by the boundary lines in the map. For each piece, the user routine
! LPR is called.
!
! Variables:
!
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: NCD, MCS, MAI
! REAL, INTENT(IN ) :: XCD(NCD), YCD(NCD)
! REAL, INTENT( OUT) :: XCS(MCS), YCS(MCS)
! INTEGER, INTENT( OUT) :: IAI(MAI), IAG(MAI)
!
! INTERFACE
! SUBROUTINE LPR( XCS, YCS, NCS, IAI, IAG, NAI )
! IMPLICIT NONE
! INTEGER, INTENT(IN) :: NCS, NAI
! REAL, INTENT(IN) :: XCS(NCS), YCS(NCS)
! INTEGER, INTENT(IN) :: IAI(NAI), IAG(NAI)
! END SUBROUTINE LPR
! END INTERFACE
!
! OPTIONAL :: DBR
! INTERFACE ! same as ARDBPA
! SUBROUTINE DBR( IAM, IGI, LAB )
! IMPLICIT NONE
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: IGI
! CHARACTER(*), INTENT(IN ) :: LAB
! END SUBROUTINE DBR
! END INTERFACE
!
! IAM is the array holding the area map, created by prior calls to the
! routines ARINAM and AREDAM.
!
! The arrays XCD and YCD hold the NCD coordinates of the points defining
! the polyline. Coordinates are given in the current user system, as
! defined by the last SET call.
!
! The arrays XCS and YCS are used, in a call to LPR, to hold the X
! and Y coordinates of points defining a particular subline. Each is
! dimensioned MCS.
!
! The arrays IAG and IAI are used, in a call to LPR, to hold group and
! area identifiers of the subline defined by XCS and YCS. Each is
! dimensioned MAI.
!
! LPR is the user's line-processing routine. It must be declared in
! an EXTERNAL statement in the routine which calls ARDRLN. It will be
! called using a statement like
!
! CALL LPR (XCS,YCS,NCS,IAI,IAG,NAI)
!
! where XCS and YCS hold the normalized device coordinates of NCS points
! defining a portion of the original polyline and IAI and IAG hold NAI
! area-identifier/group-identifier pairs for the area within which that
! piece of the polyline lies.
!
! DBR is a user version of the AREAS routine "ARDBPA". ARDRAN invokes
! ARPRAM and pass DBR to doing the debug work, that allows user to use
! larger characters for the area identifiers and/or to omit edge
! segments that are too close to the edge of the plotter frame. If DBR
! is PRESENT, ARDBPA will be replaced
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARSCAM (IAM,XCS,YCS,MCS,IAI,IAG,MAI,APR,DBR)
!
! The routine ARSCAM is called to scan an area map created by calls to
! ARINAM and AREDAM. For each subarea of the map, the user routine APR
! is called.
!
! Variables:
!
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: MAI, MCS
! REAL, INTENT( OUT) :: XCS(MCS), YCS(MCS)
! INTEGER, INTENT( OUT) :: IAI(MAI), IAG(MAI)
!
! INTERFACE
! SUBROUTINE APR( XCS, YCS, NCS, IAI, IAG, NAI )
! IMPLICIT NONE
! INTEGER, INTENT(IN) :: NCS, NAI
! REAL, INTENT(IN) :: XCS(NCS), YCS(NCS)
! INTEGER, INTENT(IN) :: IAI(NAI), IAG(NAI)
! END SUBROUTINE APR
! END INTERFACE
!
! OPTIONAL :: DBR
! INTERFACE ! same as ARDBPA
! SUBROUTINE DBR( IAM, IGI, LAB )
! IMPLICIT NONE
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: IGI
! CHARACTER(*), INTENT(IN ) :: LAB
! END SUBROUTINE DBR
! END INTERFACE
!
! IAM is the array holding the area map, created by prior calls to the
! routines ARINAM and AREDAM.
!
! The arrays XCS and YCS are used, in a call to APR, to hold the X
! and Y coordinates of the points defining a particular subarea. Each
! is dimensioned MCS.
!
! The arrays IAG and IAI are used, in a call to APR, to hold the
! group and area identifiers of the subarea defined by XCS and YCS.
! Each is dimensioned MAI.
!
! APR is the user's area-processing routine. It must be declared in
! an EXTERNAL statement in the routine which calls ARSCAM. It will be
! called using a FORTRAN statement like
!
! CALL APR (XCS,YCS,NCS,IAI,IAG,NAI)
!
! where XCS and YCS hold the normalized device coordinates of NCS points
! defining a single subarea (point number NCS being a duplicate of point
! number 1) and IAI and IAG hold NAI area-identifier/group-identifier
! pairs for that subarea.
!
! DBR is a user version of the AREAS routine "ARDBPA". ARSCAM invokes
! ARPRAM and pass DBR to doing the debug work, that allows user to use
! larger characters for the area identifiers and/or to omit edge
! segments that are too close to the edge of the plotter frame. If DBR
! is PRESENT, ARDBPA will be replaced
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARPRAM (IAM,IF1,IF2,IF3,DBR)
!
! Examine the area map. Find points of intersection, delete redundant
! edge segments, and adjust the area identifiers.
!
! Variables:
!
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: IF1, IF2, IF3
!
! OPTIONAL :: DBR
! INTERFACE ! same as ARDBPA
! SUBROUTINE DBR( IAM, IGI, LAB )
! IMPLICIT NONE
! INTEGER, INTENT(INOUT) :: IAM(*)
! INTEGER, INTENT(IN ) :: IGI
! CHARACTER(*), INTENT(IN ) :: LAB
! END SUBROUTINE DBR
! END INTERFACE
!
! IAM is the array which holds an area map previously initialized by a
! call to ARINAM and augmented by calls to AREDAM.
!
! IF1 specifies what kind of search is made for intersections. If IF1
! is zero, all pairs of edge segments which could possibly intersect
! are examined for actual intersection, a very time-consuming process.
! If IF1 is one, a pair is examined only if one of its members has a
! left or a right identifier less than or equal to zero; this saves a
! lot of time and is intended for use with contour lines.
!
! IF2 specifies what kind of action is taken to remove unclosed edges.
! If IF2 is zero, a search is made for such edges and they are simply
! removed from the area map. If IF2 is one, no such search is made;
! all edges are assumed closed.
!
! IF3 specifies what kind of search is made for area identifiers to be
! changed. If IF3 is zero, all edges of all subareas are examined in
! complete detail, a very time-consuming process. If IF3 is one, only
! those edges having a zero or negative area identifier are examined
! (all others being assumed correct) and holes are ignored, which saves
! a lot of time; this is intended for use with contour lines.
!
! DBR is a user version of the AREAS debug routine "ARDBPA" that allows
! user to use larger characters for the area identifiers and/or to omit
! edge segments that are too close to the edge of the plotter frame.
! If DBR is PRESENT, ARDBPA will be replaced.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARDBPA (IAMA,IGIP,LABL)
!
! The routine ARDBPA produces a picture of that part of the contents of
! the area map IAMA which belongs to the group IGIP; if IGIP is zero or
! negative, all groups of edges are shown. The character string LABL
! will be used as a label for the picture.
!
! Variables:
!
! INTEGER, INTENT(INOUT) :: IAMA(*)
! INTEGER, INTENT(IN ) :: IGIP
! CHARACTER(*), INTENT(IN ) :: LABL
!
!---------------------------------------------------------------------
!
! SUBROUTINE ARMVAM (IAM,IAN,LAN)
!
! Move an area map from one integer array (IAM) to another (IAN). The
! length of the first area map can be inferred from its contents; the
! length of the second one is given by the value of the argument LAN.
!
! Variables:
!
! INTEGER, INTENT(IN ) :: LAN
! INTEGER, INTENT(INOUT) :: IAM(*), IAN(*)
!
!=====================================================================
! Internal parameters:
!=====================================================================
!
! IDB ("Debug Plots") is of type INTEGER.
! If non-zero, it specifies the identifier of the group of edge
! segments to be depicted on debug plots done by ARPRAM. Use a
! "-1" to see all groups of edge segments.
! The default value is 0
!
! IDC ("Debug Colors") is of type INTEGER.
! If debug plots are done, color indices 'DC'+1 through 'DC'+5
! should have been defined (by user) for use on the plots.
! The default value is 100
!
! RID ("Identifier Distance") is of type REAL.
! It specifies the distance from an edge to an identifier on a
! debug plot, stated as a fraction of the distance across the
! plotter frame.
! The default value is 0.004
!
! RIS ("Identifier Size") is of type REAL.
! It specifies the size (width) of characters used to write
! identifiers on a debug plot, stated as a fraction of the
! distance across the plotter frame.
! The default value is 0.001
!
! RAL ("Arrowhead Length") is of type REAL.
! It specifies the length of the arrowheads to be used on debug
! plots, stated as a fraction of the distance across the plotter
! frame.
! The default value is 0.008
!
! RAW ("Arrowhead Width") is of type REAL.
! It specifies the width of the arrowheads to be used on debug
! plots, stated as a fraction of the distance across the plotter
! frame. RAW is actually half the width of an arrowhead.
! The default value is 0.002
!
! LTI ("Timing Information") is of type LOGICAL.
! Either activates (.TRUE.) or eliminates (.FALSE.) printing of
! timing information on debug plots.
! The default value is .FALSE.
! *** can be set/get by ARSET0/ARGET0 only
!
! ------------------
!
! IAT ("Arithmetic Type") is of type INTEGER.
! It specifies the type of arithmetic to be used by AREAS.
! =0 allows AREAS to decide what type of arithmetic to
! =1 forces the use of real arithmetic.
! =2 forces the use of double-precision arithmetic.
! =3 forces the use of multiple-precision arithmetic.
! The default value is 0
!
! ILC ("Largest Coordinate") is of type INTEGER.
! It specifies the resolution of the grid used by AREAS to
! represent the plotter frame.
! The default value is 1000000
!
! ------------------
!
! IRC ("Resolving-Contradictions flag array") refers to a 16-element
! array, indexed by group identifier, of type INTEGER.
! Values in it determine in what manner contradictions in the
! area-identifier information for an area are to be resolved.
! The default value is (/0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0/)
!
! For IGI = 1 to 16, IRC(IGI) says how to reconcile contradictory
! area-identifier information for group IGI. (Groups with group
! identifiers greater than 16 are affected by IRC(16).)
!
! The default value of IRC(IGI) is zero, which says to do it the
! original way, using the most recently-provided information for
! a given area.
!
! The value 1 says to do it a new way, using that area identifier
! seen most frequently, but ignoring zeroes; the value 2 says to
! do it the new way, but not to ignore zeroes.
!
! The values -1 and -2 mean the same as 1 and 2, respectively,
! except that, if there are any negative values among the set of
! possible area identifiers for a given area, then a -1 is used
! for the area.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARRSET()
! SUBROUTINE NG_ARSET0()
!
! Routine to reset all internal parameters to its default values.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARSET1( IAT, ILC, IDB, RID, RIS, RAL, RAW, LTI, IRC )
!
! Routine to set internal parameters of AREAS
!
! Variables:
!
! INTEGER, INTENT(IN), OPTIONAL :: IAT, ILC, IDB, IRC
! REAL, INTENT(IN), OPTIONAL :: RID, RIS, RAL, RAW
! LOGICAL, INTENT(IN), OPTIONAL :: LTI
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARGET1( IAT, ILC, IDB, RID, RIS, RAL, RAW, LTI, IRC )
!
! Routine to get internal parameters of AREAS
!
! Variables:
!
! INTEGER, INTENT(OUT), OPTIONAL :: IAT, ILC, IDB, IRC
! REAL, INTENT(OUT), OPTIONAL :: RID, RIS, RAL, RAW
! LOGICAL, INTENT(OUT), OPTIONAL :: LTI
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARSETI( IPN, IVL )
!
! This subroutine is called to set the integer value of a specified
! parameter.
!
! Variables:
!
! CHARACTER(*), INTENT(IN) :: IPN
! INTEGER, INTENT(IN) :: IVL
!
! IPN is the name of the parameter whose value is to be retrieved.
! IPN(1:2) =
! 'DB', "Debug Plots", is the parameter IDB
! 'DC', "Debug Colors", is the parameter IDC
! 'ID', "Identifier Distance", is the parameter RID
! 'IS', "Identifier Size", is the parameter RIS
! 'AL', "Arrowhead Length", is the parameter RAL
! 'AW', "Arrowhead Width" , is the parameter RAW
! 'AT', "Arithmetic Type", is the parameter IAT
! 'LC', "Largest Coordinate", is the parameter ILC
! 'RC', "Resolving-Contradictions", is the parameter IRC
!
! IVL is an integer variable containing the desired new value.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARSETR( IPN, RVL )
!
! This subroutine is called to set the real value of a specified
! parameter.
!
! Variables:
!
! CHARACTER(*), INTENT(IN) :: IPN
! REAL, INTENT(IN) :: RVL
!
! IPN is the name of the parameter whose value is to be retrieved.
! IPN(1:2) =
! 'DB', "Debug Plots", is the parameter IDB
! 'DC', "Debug Colors", is the parameter IDC
! 'ID', "Identifier Distance", is the parameter RID
! 'IS', "Identifier Size", is the parameter RIS
! 'AL', "Arrowhead Length", is the parameter RAL
! 'AW', "Arrowhead Width" , is the parameter RAW
! 'AT', "Arithmetic Type", is the parameter IAT
! 'LC', "Largest Coordinate", is the parameter ILC
! 'RC', "Resolving-Contradictions", is the parameter IRC
!
! RVL is a real variable containing the desired new value.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARGETI( IPN, IVL )
!
! This subroutine is called to retrieve the integer value of a specified
! parameter.
!
! Variables:
!
! CHARACTER(*), INTENT(IN ) :: IPN
! INTEGER, INTENT( OUT) :: IVL
!
! IPN is the name of the parameter whose value is to be retrieved.
! IPN(1:2) =
! 'DB', "Debug Plots", is the parameter IDB
! 'DC', "Debug Colors", is the parameter IDC
! 'ID', "Identifier Distance", is the parameter RID
! 'IS', "Identifier Size", is the parameter RIS
! 'AL', "Arrowhead Length", is the parameter RAL
! 'AW', "Arrowhead Width" , is the parameter RAW
! 'AT', "Arithmetic Type", is the parameter IAT
! 'LC', "Largest Coordinate", is the parameter ILC
! 'RC', "Resolving-Contradictions", is the parameter IRC
!
! IVL is an integer variable in which the desired value is to be
! returned by ARGETI.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_ARGETR( IPN, RVL )
!
! This subroutine is called to retrieve the real value of a specified
! parameter.
!
! Variables:
!
! CHARACTER(*), INTENT(IN ) :: IPN
! REAL, INTENT( OUT) :: RVL
!
! IPN is the name of the parameter whose value is to be retrieved.
! IPN(1:2) =
! 'DB', "Debug Plots", is the parameter IDB
! 'DC', "Debug Colors", is the parameter IDC
! 'ID', "Identifier Distance", is the parameter RID
! 'IS', "Identifier Size", is the parameter RIS
! 'AL', "Arrowhead Length", is the parameter RAL
! 'AW', "Arrowhead Width" , is the parameter RAW
! 'AT', "Arithmetic Type", is the parameter IAT
! 'LC', "Largest Coordinate", is the parameter ILC
! 'RC', "Resolving-Contradictions", is the parameter IRC
!
! RVL is a real variable in which the desired value is to be
! returned by ARGETR.
!
!=====================================================================
! Refer "NCAR menu" for interfacing AREAS in detail
!=====================================================================