# coyote: CGDRAWVECTORS

- coyote/Graphics
- [Source code]

Description

      Plots the velocity vectors of particles at their position. Vectors may be
      overplotted onto other IDL graphics plots.
      The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
      to be installed on your machine.

Categories

      Graphics

Params

      velx: in, required, type=integer/float
           An array containing the X component of the particle velocity vector.
      vely: in, required, type=integer/float
           An array containing the Y component of the particle velocity vector.
      posx_: in, required, type=integer/float
           An array containing the X posiiton of the particle velocity vector. The
           shaft end of the arrow vector is positioned here.
      posy_: in, required, type=integer/float
           An array containing the Y posiiton of the particle velocity vector. The
           shaft end of the arrow vector is positioned here.

Keywords

      addcmd: in, optional, type=boolean, default=0
          An alternative way to set the `Window` keyword.
      clip: in, optional, type=boolean, default=0
          Set the keyword to clip vector output to the clipping rectangle specified
          in the `CRect` keyword. See the documentation for the IDL graphics
          keyword NOCLIP.
      crect: in, optional, type=float
           A four-element array giving the clipping rectangle [xo, yo, x1, y1]. The
           default clipping rectangle is the plot area. See the documenation for the
           IDL graphics keyword CLIP.
      device: in, optional, type=boolean, default=0
          Set this keyword to indicate the vector positions are given in
          device coordinates. Data coordinates are assumed.
      fraction: in, optional, type=float, default=1.0
          A number between 0.0 and 1.0 indicating the fraction of the vectors to
          draw on the plot. Vectors are selected randomly from the total population,
          unless the `Ordered` keyword is set, in which case they are selected
          in an ordered, systematic fashion. For example, Fraction=0.5 will select
          every other input vector.
      hsize: in, optional, type=float
          The size of the the arrow head. By default 1/100th the width
          of the device. (!D.X_SIZE / 100.)
      hthick: in, optional, type=float
          The thickness of the line drawing the arrowhead of the vector. The
          default is 3 for the PostScript device and 1 for all other devices.
      length: in, optional, type=float, default=0.075
          The length of the `ReferenceVector` in normalized units. All vectors
          are scaled according to this length.
      linestyle: in, optional, type=integer, default=0
          The line style of the arrow. Line style integers as in PLOT.
      mapCoord: in, optional, type=object
          A map coordinate object (e.g., cgMap) that describes the map projection
          and datum used to specify the vector locations. Note that this could also be a
          map structure as returned from MAP_PROJ_INIT, but in that case the user is
          responsible for setting up the XY map coordinate space independently and
          outside of this program. This coordinate object will be used to transform
          lat/lon locations into the XY locations of the map projection.
      normal: in, optional, type=boolean, default=0
          Set this keyword to indicate the vector positions are given in
          normalized coordinates. Data coordinates are assumed.
      ordered: in, optional, type=boolean, default=0
          If this keyword is set, and the `Fraction` keyword is used, the fraction
          of vectors used in the plot are chosen from the entire population in a
          systematic, ordered fashion.
      overplot: in, optional, type=boolean, default=0
          Set this keyword to overplot the vectors on an established coordinate
          system plot.
      referencevector: in, optional, type=float
          The magnitude of a reference vector that is used to scale all other vectors before display.
          If undefined, 75 percent of the maximum vector magnitude.
      solid: in, optional, type=boolean, default=0
          Set this keyword to draw solid, filled arrows.
      thick: in, optional, type=float
          The thickness of the line drawing the shaft of the arrow. The
          default is 3 for the PostScript device and 1 for all other devices.
      veccolors: in, optional
          A scalar or vector of colors the same size as `velx`. May be bytes, short integers,
          or strings. Bytes and short integers are treated as indices into the current color
          table. The default is "opposite".
      window: in, optional, type=boolean, default=0
          Set this keyword to add the command to an cgWindow application.
      xrange: in, optional, type=float
          If a plot is to be drawn, the X range of the plot. By default, the X range is
          calculated to contain all of the velocity vectors.
      yrange: in, optional, type=float
          If a plot is to be drawn, the Y range of the plot. By default, the Y range is
          calculated to contain all of the velocity vectors.
      _extra: in, optional
          Any keywords appropriate for the cgPlot command can be used to create the plot.

Examples

      Generate some particle positions and velocities::
           posx = RandomU(seed,200)
           posy = RandomU(seed,200)
           velx = RandomU(seed,200)-0.5
           vely = RandomU(seed,200)-0.5
      Plot the particle velocities::
           cgDrawVectors, velx, vely, posx, posy
      Example using vector colors::
           magnitude = SQRT(velx^2 + vely^2)
           cgLoadCT, 5
           colors = BytScl(magnitude)
           cgDrawVectors, velx, vely, posx, posy, VecColors=colors
      Example using a map projection::
            posx = Indgen(10)*36
            posy = Replicate(30,10)
            velx = Replicate(10.,10) ; Wind out of the West
            vely = Replicate(0, 10)  ; No vertical component
            cgDisplay
            mapNorth = Obj_New('cgMap', 'Polar Stereographic', $
                  Limit=[0, -180, 90, 180], /NoBorder)
            mapNorth -> Draw
            cgMap_Continents, Color='black', Map_Structure=mapNorth
            cgMap_Grid, LatDel=15, LonDel=15, LineStyle=1, Color='charcoal', $
                  /Label, LonLabel=2, Map_Structure=mapNorth
            cgDrawVectors, velx, vely, posx, posy, VecColors='blu6', /Overplot, $
                  ReferenceVector=10, /Solid, Thick=2, MapCoord=mapNorth

Author

      FANNING SOFTWARE CONSULTING::
          David W. Fanning
          1645 Sheely Drive
          Fort Collins, CO 80526 USA
          Phone: 970-221-0438
          E-mail: david@idlcoyote.com
          Coyote's Guide to IDL Programming: http://www.idlcoyote.com

History

      Change History::
         Written by David Fanning, based on NASA Astronomy Library program PartVelVec, 22 March 2014
         Added ORDERED keyword. 24 March 2014. DWF.
         Drawing the vectors All Wrong. Using what I think is the correct algorithm now. 24 March 2014. DWF.
         Modified so I don't change into position variables. 24 March 2014. DWF.
         Fixed a small problem with the algorithm for calculating the direction of the scaled vectors and
            added CLIP and CRECT keywords. 25 March 2014. DWF.
         Added MAPCOORD keyword. 27 March 2014. DWF.
         Modified to set color information once here, instead of allowing cgArrow to do it. 27 March 2014. DWF.
         Some map projections (e.g., polar stereographic) can change the direction of the vector on the
            projected map. To solve this problem, I needed to create a second point in the original coordinate
            system and project both points into the map coordinate system before calculating the angle
            between points. Also then had to figure out how to scale the moved point to the reference
            vector. All appears normal now. 2 Nov 2014. DWF.
         Still a couple of problems in the direction of the vector when the scale is different in the X and
            Y directions. This version of the program allows the vector to be distorted by scale and by a map
            projection. It more closely resembles the NASA program PartVelVec now than it did previously.
            18 Feb 2015. DWF.
         “To kill an error is as good a service as, and sometimes even better than, the establishing of a
            new truth or fact,” asserted Charles Darwin. In that vein, I have completely gutted the internal
            vector placing algorithm in cgDrawVectors and replaced it with an algorithm that essentially
            duplicates the vectors of the NASA Astronomy Library routine PartVelVec. The essential change was
            to take into account the plot scale in both the X and Y direction when computing the end point
            of a vector. You will see an "aspect" variable in the code. When being placed on map projections,
            using either cgMap_Set or cgMap, the aspect ratio of 180./360. is always used. The aspect ratio is
            used to scale the vector components before placement of the vector. 23 February 2015. DWF.
         Well, duh! Had the WINDOW keyword set when I passed this to a cgWindow. This started a beautiful
            infinite loop! Removed. 11 Nov 2016. DWF.
         Fixed a problem with default vector colors not being byte values. 11 Nov 2016. DWF.

Copyright

      Copyright (c) 2014-2016, Fanning Software Consulting, Inc.