Index   |   map > dataplot.m
<<  Contents toposurf  >>
dataplot
PURPOSE ^
DATAPLOT Plot a DataSet from a DataFile using Styles from a StyleFile
SYNOPSIS ^
function [msg,h,al,hp,ht] = dataplot(DataFile,StyleFile,varargin);
DESCRIPTION ^
 DATAPLOT  Plot a DataSet from a DataFile using Styles from a StyleFile

 Msg = DATAPLOT( DataFile , StyleFile , [Axe] , [ConfigFile] , ... )

 see below for StyleConfigurations and DataSyntax

*************************************************************************
 Inquire the Configuration

 [Msg,CNF,INI]    = DATAPLOT  returns the DefaultConfiguration

 [Msg,CNF,File]   = DATAPLOT('@FILENAME') saves a DefaultConfigFile

 [Msg,ConfigHelp] = DATAPLOT('@-') returns ConfigHelpText
 [Msg,ConfigHelp] = DATAPLOT('@%') returns ConfigHelpText, prepended with "%"

 [Msg,StylesHelp] = DATAPLOT('#-') returns StylesHelpText
 [Msg,StylesHelp] = DATAPLOT('#%') returns StylesHelpText, prepended with "%"


*************************************************************************
 See also:

 Configuration:   LOAD_CNF, CHECK_CNF, STRUCTCHK, DEFVAL, LOAD_ASC

 Colors:          FERRETC, COLSPEC, XRGB, XRGBROWSE

 Arrows/Stripes:  ARROWS, STRIPES

 Move:            AXEMOVE, OBJMOVE, TEXTMOVE

*************************************************************************
 Configuration
*************************************************************************

 Below the Configuration of DATAPLOT, which can also be written in a
  ConfigFile to load by LOAD_ASC.
  The KeyWordMarker are {'#' ':'}, the CommentMarker '%'.

 Use normal MatlabSyntax for Values in ConfigFile.
 Mask Marker in Values with surrounding "", like: "#"

 Example:

 # Order: 'geo'   % Use Lat/Lon-Pairs !!!
 # FaceColor
 % Color for LegendFrame
    1  1  1

 Note: The Parameter (Keywords) must be written in the correct
        Upper/Lower-Case-Statement.

       Not all Parameter (Keywords) must be defined in a ConfigFile.
       For undefined Parameter the defaults are used.

       Parameter, defined in the Inputs of DATAPLOT, overwrite
        the defaults or Values from ConfigFile.

       To use the Functionalities of MoveObjects and MoveLegend,
        the Functions TEXTMOVE, OBJMOVE, AXEMOVE must be exist
        in Matlab's SearchPath!
       They can be found in the "private"-Directory of DATAPLOT.
        or in the SubDirectory "tools/move/"

-------------------------------------------------------------------------

 Valid ColorSpecifier by the Optional Value '#colspecX#':

  Matlab: 'r'   'g'     'b'    'c'    'm'       'y'      'k'     'w'
          'red' 'green' 'blue' 'cyan' 'magenta' 'yellow' 'black' 'white'

    XRGB: type >> xrgbrowse
            or >> xrgb
            or >> colspec(1)


 Statements for required Size:

  "-"   any Size in this Dimension allow
  "-N"  Value can have a Size up to N in this Dimension
  "N"   Value must have Size N in this Dimension
        Single Values will repeated by N
        Longer Sizes are cutted.

-------------------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------------------
 Order         'xy' 'geo'                       Order of XY-Coordinates,
                                                'geo': [ Lat Lon ]
                                                #default: 'geo'

 PointScale     [ 1  1 ]  numeric               ScaleFactor for Properties in Units [points]
               'none'                            like: FontSize, LineWidth, MarkerSize
                                                used for Data and Legend
                                                #default: 'none'

 MoveObjects   'off' 'data' 'style'             Enable moving of Objects with Mouse by OBJMOVE.
                                                'data':  Move Objects of equal Data together
                                                'style': Move Objects of equal Data and Style together
                                                #default: 'off'

 MoveLegend    'off' 'on'                       Enable moving of LegendFrames by AXEMOVE.
                                                #default: 'off'

 Number         [ 1  1 ]  uint8                 Max. Number of LegendFrames to Show
               'auto'                            0: No LegendFrames, "+i" Number of Entries per Legend
                                                #default: 'auto'

 Position       [ -  -4 ]  numeric              XY-Position  [ XPos  YPos ] of LegendFrames in Axes
               'auto'                           The SIGN defines the Alignment of the LegendFrame:
                                                "+" Align Frame with   Left/Bottom - Corner
                                                "-" Align Frame with  Right/Top    - Corner
                                                The Position is measured from Left/Bottom Corner of Axes,
                                                 a NonZero imaginary Part "+i" measures from Right/Top.
                                                The Units are normalized, Values with ABS >= 3 are used in Pixels.
                                                A NaN for XPos xor YPos will use the Distance of the Other
                                                  in the same Aspect, use the SIGN of the imaginary Part "+i" / "-i"
                                                  to define the Aligment and AxesCorner
                                                A 3. Column set the Alignment of LegendEntries:
                                                     0 = Vertical (default), 1 = Horizontal
                                                A 4. Column set an individual AspectRatio for LegendObjects,
                                                     Width/Height for LegendPatches, NaN use the DefaultAspect
                                                #default: 'auto'

 Space          [ 1  2 ]  numeric               Vert/Horiz Space between LegendEntries
                                                 units: Height of LegendFont
                                                #default: [ 0.5  2 ]

 Aspect         [ 1  1 ]  numeric               DefaultAspectRatio for Size of LegendObjects
                                                 Width/Height for LegendPatches
                                                #default:   1.618

 Scale          [ 1  1 ]  numeric               ScaleFactor for Properties in Units [points]
               'none'                            like: LineWidth, MarkerSize
                                                used for Data in Legend
                                                #default: 'none'

 Offset         [ 1  -4 ]  uint8                Additional PixelOffset for LegendObjects in LegendFrame
                                                [ Left Right Bottom Top ] | LRBT | [ LR BT ] | [ L R BT ]  pixels
                                                "+i" measures direct, ignore DefaultOffset
                                                #default:   0

 Radius         [ 1  1 ]  uint8                 Radius [pixel] for Edges of LegendFrame
                                                #default:   0

 LineWidth      [ 1  1 ]  numeric               LineWidth of LegendFrame, scaled by PointScale
                                                #default:   1

 EdgeColor      [ 1  3 ]  numeric               EdgeColor of LegendFrame
               'none' '#colspecX#'              #default: 'k'

 FaceColor      [ 1  3 ]  numeric               FaceColor of LegendFrame
               'none' '#colspecX#'              #default: 'w'

 FaceAlpha      [ 1  1 ]  numeric               AlphaValue for FaceColor of LegendFrame
                                                #default:   1

 FontColor      [ 1  3 ]  numeric               Color of LegendText
               '#colspecX#'                     #default: 'k'

 FontSize       [ 1  1 ]  uint8                 FontSize of LegendText, scaled by PointScale
                                                #default:   12

 FontName       [ 1  - ]  char                  FontName of LegendText
                                                #default: 'helvetica'

 FontWeight    'light' 'normal' 'demi' 'bold'   FontWeight of LegendText
                                                #default: 'bold'

 FontAngle     'normal' 'italic' 'oblique'      FontAngle of LegendText
                                                #default: 'normal'


 DataMarker     [ 1  -2 ]  cellstr              KeywordMarker in StyleFile, { Start [End] }
                                                #default: { '#' , ',' }

 DataComment    [ 1  1 ]  char                  CommentMarker in DataFile
                                                #default: '%'

 Separator      [ 1  -1 ]  char                 SeperatorCharacter for multiple Styles
                                                 in DataKeyword
                                                #default: ' '

 DataOrder     'normal' 'reverse'               Order to draw multiple Styles for Data
                                                #default: 'normal'

 StyleMarker    [ 1  -2 ]  cellstr              KeywordMarker in StyleFile, { Start [End] }
                                                #default: { '#' , ':' }

 StyleComment   [ 1  1 ]  char                  CommentMarker in StyleFile
                                                #default: '%'

 StyleOrder    'normal' 'reverse'               Order to draw multiple Types for Style
                                                #default: 'normal'


*************************************************************************
 Configuration for Styles: TEXT  MARKER  AREA  LINE  PATCH  ARROW
*************************************************************************

 The Styles are written in the StyleFile, to load by LOAD_ASC.
 A Style can have multiple Types (Configurations).
 Missing Fields are replaced with defaults.

 A DataFile refers with the Keywords to the Styles.
 A DataKeyWord can have multiple Styles, separated by the Separator " "

  The KeyWordMarker for a StyleFile are {'#' ':'}, the CommentMarker '%'.

  The KeyWordMarker for a  DataFile are {'#' ','}, the CommentMarker '%'.

 Use normal MatlabSyntax for Values in ConfigFile.

 KeyWords can be used as VariableNames in Values of following KeyWords.

  example:  # FN: 'helvetica'
            # T1: 'text' 12 'k' FN 'bold'
            # T2: 'text' 10 'k' FN 'normal'

=========================================================================
 Available Types for Styles (see below for detailed Description)

----------------------------------------------------------------------
 TEXT

 'text'   FontSize  Color  FontName  FontWeight  FontAngle  ...
   ShadowNumber  ShadowColor  ShadowWidth  ShadowShift

----------------------------------------------------------------------
 MARKER

 Marker  MarkerSize  LineWidth  MarkerEdgeColor  MarkerFaceColor

----------------------------------------------------------------------
 AREA

 'area'   Number  Radius  LineStyle  LineWidth  EdgeColor  FaceColor  ...
   StripeDistance  StripeAngle  StripeColor  StripeWidth  StripeStyle

----------------------------------------------------------------------
 LINE

 'line'   LineStyle  LineWidth  Color  SplineNumber  SplinePotenz

----------------------------------------------------------------------
 PATCH

 'patch'   LineStyle  LineWidth  EdgeColor  FaceColor  ...
   StripeDistance  StripeAngle  StripeColor  StripeWidth  StripeStyle

----------------------------------------------------------------------
 ARROW

 'arrow'   LineStyle  LineWidth  EdgeColor  FaceColor  ...
   Number  Resolution  Shape  Offset  Length  Distance


=========================================================================
 Examples

----------------------------------------------------------------------
 Example for a StyleFile (write this to "style_demo.cnf"):
----------------------------------------------------------------------

   # M                           % Defines Style M, Types: Line, Marker
     'line'  '-'  2  'g'
     'o'     12   3  'k'  'y'

   # L: 'line' '-' 1 'r' 100     % Draw an 100-Point Spline

   # T: 'text'  12  'k' 'courier' 'bold'

   # A
     'arrow'  '-' 3 'k' 'b' 2   % 2 Arrows per NaN-separated LineSegments

   # P
     'patch'  '-' 1 'k' 'none' 15 [ 30 150 ]  % Patch with 2 Stripes

----------------------------------------------------------------------
 Example for a DataFile (write this to "data_demo.cnf"):
----------------------------------------------------------------------

   # A,   'An Arrow'                  % A LegendEntry
   # P,   'Patch with Stripes'        % another
   # M,   'Line with Marker'          % ...
   # M A, 'Marker, Line and Arrow'

   # M , 10 20 , 20 30 , 45 50    % A Line with Marker

   # T M, 'Test' 25 30 0 0 1 0 1  % Text and Marker at Position
                                  %   shift Text Vertical

   # A                            % Arrows along NaN-separated LineSegments
       30  10
       20  05
       10  05
       05  00
      NaN NaN
       10  10
       50  50

   # M L,  15 10  40 15  40 25  50 35

   # P, 10 30  25  45  15  50  5 40

----------------------------------------------------------------------
 Run the Example from "style_demo.cnf" and "data_demo.cnf":
----------------------------------------------------------------------

  figure, dataplot data_demo.cnf style_demo.cnf  % Up's, no Axes defined

  figure,
  dataplot('data_demo.cnf','style_demo.cnf',gca,'Number',0)  % No Legend

  figure, axis([0 100 0 100])
  dataplot data_demo.cnf style_demo.cnf Order xy

  figure, axis([0 100 0 100])
  dataplot('data_demo.cnf','style_demo.cnf', ...
           'StyleOrder','reverse');

  figure, axis([0 100 0 100])
  dataplot('data_demo.cnf','style_demo.cnf', 'Number' , 2+2*i , ...
           'StyleOrder','reverse','DataOrder','reverse');


=========================================================================

 For multiple Types in a Style in extended Syntax fill Fields with "[]"

 Valid ColorSpecifier by the Optional Value '#colspecX#':

  Matlab: 'r'   'g'     'b'    'c'    'm'       'y'      'k'     'w'
          'red' 'green' 'blue' 'cyan' 'magenta' 'yellow' 'black' 'white'

    XRGB: type >> xrgbrowse
            or >> xrgb
            or >> colspec(1)

=========================================================================
 Description of Types

=========================================================================
 TEXT

 'text'   FontSize  Color  FontName  FontWeight  FontAngle  ...
   ShadowNumber  ShadowColor  ShadowWidth  ShadowShift

-------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------

 Init_          'text'                           DataSyntax for TextData:
                                                  { String  X  Y  Rot XOff YOff Horiz Vert }
                                                  use "Lat Lon" instead of "X Y" in case of Order 'geo'
                                                  use a NonZero imaginary Part for X/Y for normalized Units
                                                   the SIGN of the imaginary Part refers to:
                                                    "+": Left/Bottom, "-": Right/Top
                                                 XOff and YOff are measured in CharacterUnits
                                                 The SIGN of Horiz and Vert defines the Alignment:
                                                  Horiz = [ -1  0  1 ] ( Right Center Left )
                                                  Left  = [ -1  0  1 ] ( Cap Middle BaseLine )
                                                 #default: 'text'

 FontSize        [ 1  1 ]  uint8                 #default:   10

 Color           [ 1  3 ]  numeric               #default: 'k'
                'none' '#colspecX#'

 FontName        [ 1  - ]  char                  #default: 'helvetica'

 FontWeight     'light' 'normal' 'demi' 'bold'   #default: 'normal'

 FontAngle      'normal' 'italic' 'oblique'      #default: 'normal'

 ShadowNumber_   [ 1  1 ]  uint8                 Number of surrounding ShadowText's
                                                  0: No Shadow
                                                 #default:   0

 ShadowColor_    [ 1  3 ]  numeric               Color of Shadow,
                'none' 'auto' '#colspecX#'       'none': No Sadow, 'auto': inverted Color
                                                 #default: 'auto'

 ShadowWidth_    [ 1  1 ]  numeric               Width of surreounding Shadow in [points]
                                                  0: No Shadow
                                                 #default:   2

 ShadowShift_    [ 1  2 ]  numeric               Shift of Shadow: [ Radius[points] Direction[deg] ]
                                                 #default: [ 0  0 ]


=========================================================================
 MARKER

 Marker  MarkerSize  LineWidth  MarkerEdgeColor  MarkerFaceColor

-------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------

 Marker            [ 1  - ]  char       Style of Marker, use any of:
                                         +  o  *  .  x  s  d
                                         v  ^  >  <  p  h
                                        Specials: (  )  u  ~  none
                                        One Marker per Point is Shown
                                        DataSyntax: [ X1 Y1 , X2 Y2 , ... ]
                                         use [ Lat Lon ]-Pairs in case of Order 'geo'
                                         use a NonZero imaginary Part for normalized Units
                                          the SIGN of the imaginary Part refers to:
                                           "+": Left/Bottom, "-": Right/Top
                                        #default: 'o'

 MarkerSize        [ 1  1 ]  uint8      #default:   8

 LineWidth         [ 1  1 ]  numeric    #default:   1

 MarkerEdgeColor   [ 1  3 ]  numeric    #default: 'k'
                  'none' '#colspecX#'

 MarkerFaceColor   [ 1  3 ]  numeric    #default: 'r'
                  'none' '#colspecX#'


=========================================================================
 AREA

 'area'   Number  Radius  LineStyle  LineWidth  EdgeColor  FaceColor  ...
   StripeDistance  StripeAngle  StripeColor  StripeWidth  StripeStyle

-------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------

 Init_            'area'                            One Area per Point is shown
                                                    Number defines the Shape of the regular Area
                                                    DataSyntax: [ X1 Y1 , X2 Y2 , ... ]
                                                     use [ Lat Lon ]-Pairs in case of Order 'geo'
                                                     use a NonZero imaginary Part for normalized Units
                                                      the SIGN of the imaginary Part refers to:
                                                       "+": Left/Bottom, "-": Right/Top
                                                    #default: 'area'

 Number_           [ 1  1 ]  int16                  Number of Corners + Rotation*i
                                                     positive Number: Corner Top
                                                     negative Number: Corner Left
                                                    #default:   4

 Radius_           [ 1  -3 ]  uint8                 Radius of surrounding Circle/Ellipse [points]
                                                     Radius | [ RadiusX  RadiusY  Rotation ]
                                                    #default:   8

 LineStyle        '-' '--' ':' '-.' 'none'          LineStyle of AreaEdges
                                                    #default: '-'

 LineWidth         [ 1  1 ]  numeric                LineWidth of AreaEdges
                                                    #default:   1

 EdgeColor         [ 1  3 ]  numeric                LineColor of AreaEdges
                  'none' '#colspecX#'               #default: 'k'

 FaceColor         [ 1  3 ]  numeric                #default: 'none'
                  'none' '#colspecX#'

 StripeDistance_   [ 1  1 ]  uint8                  Distance between StripeLines in [points]
                                                     0: No Stripes, "+i": don't show Stripes in Legend
                                                    #default:   0

 StripeAngle_      [ 1  - ]  int16                  Angle of StripeLines to X-Axes
                                                     empty: No Stripes, multiple Angles possible
                                                    #default:   30

 StripeColor_      [ 1  3 ]  numeric                Color of StripeLines
                  'none' 'auto' '#colspecX#'        'none': No Stripes, 'auto': use EdgeColor
                                                    #default: 'auto'

 StripeWidth_      [ 1  1 ]  numeric                Width of StripeLines
                  'none' 'auto'                     'none': No Stripes, 'auto': use LineWidth
                                                    #default: 'auto'

 StripeStyle_     '-' '--' ':' '-.' 'none' 'auto'   LineStyle of StripeLines
                                                    'none': No Stripes, 'auto': use LineStyle
                                                    #default: 'auto'


=========================================================================
 LINE

 'line'   LineStyle  LineWidth  Color  SplineNumber  SplinePotenz

-------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------

 Init_          'line'                     DataSyntax: [ X1 Y1 , X2 Y2 , ... ]
                                            use [ Lat Lon ]-Pairs in case of Order 'geo'
                                            use a NonZero imaginary Part for normalized Units
                                             the SIGN of the imaginary Part refers to:
                                              "+": Left/Bottom, "-": Right/Top
                                           #default: 'line'

 LineStyle      '-' '--' ':' '-.' 'none'   #default: '-'

 LineWidth       [ 1  1 ]  numeric         #default:   1

 Color           [ 1  3 ]  numeric         #default: 'k'
                '#colspecX#'

 SplineNumber_   [ 1  1 ]  uint16          Draw a N-Point cubic Spline trougt Points
                                           #default:   0

 SplinePotenz_   [ 1  1 ]  numeric         Potenz for Distance between Points for Calculation of Spline
                                           #default:   1


=========================================================================
 PATCH

 'patch'   LineStyle  LineWidth  EdgeColor  FaceColor  ...
   StripeDistance  StripeAngle  StripeColor  StripeWidth  StripeStyle

-------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------

 Init_            'patch'                           DataSyntax: [ X1 Y1 , X2 Y2 , ... ]
                                                     use [ Lat Lon ]-Pairs in case of Order 'geo'
                                                     use a NonZero imaginary Part for normalized Units
                                                      the SIGN of the imaginary Part refers to:
                                                       "+": Left/Bottom, "-": Right/Top
                                                    Separate multiple Patches by NaN-Pairs
                                                    #default: 'patch'

 LineStyle        '-' '--' ':' '-.' 'none'          LineStyle of PatchEdges
                                                    #default: '-'

 LineWidth         [ 1  1 ]  numeric                LineWidth of PatchEdges
                                                    #default:   3

 EdgeColor         [ 1  3 ]  numeric                LineColor of PatchEdges
                  'none' '#colspecX#'               #default: 'k'

 FaceColor         [ 1  3 ]  numeric                #default: 'none'
                  'none' '#colspecX#'

 StripeDistance_   [ 1  1 ]  uint8                  Distance between StripeLines in [points]
                                                     0: No Stripes, "+i": don't show Stripes in Legend
                                                    #default:   0

 StripeAngle_      [ 1  - ]  int16                  Angle of StripeLines to X-Axes
                                                     empty: No Stripes, multiple Angles possible
                                                    #default:   30

 StripeColor_      [ 1  3 ]  numeric                Color of StripeLines
                  'none' 'auto' '#colspecX#'        'none': No Stripes, 'auto': use EdgeColor
                                                    #default: 'auto'

 StripeWidth_      [ 1  1 ]  numeric                Width of StripeLines
                  'none' 'auto'                     'none': No Stripes, 'auto': use LineWidth
                                                    #default: 'auto'

 StripeStyle_     '-' '--' ':' '-.' 'none' 'auto'   LineStyle of StripeLines
                                                    'none': No Stripes, 'auto': use LineStyle
                                                    #default: 'auto'


=========================================================================
 ARROW

 'arrow'   LineStyle  LineWidth  EdgeColor  FaceColor  ...
   Number  Resolution  Shape  Offset  Length  Distance

-------------------------------------------------------------
 Parameter        [Size]  Type / Values            Comment
                  Optional
-------------------------------------------------------------

 Init_        'arrow'                    DataSyntax: [ X1 Y1 , X2 Y2 , ... ]
                                          use [ Lat Lon ]-Pairs in case of Order 'geo'
                                          use a NonZero imaginary Part for normalized Units
                                           the SIGN of the imaginary Part refers to:
                                            "+": Left/Bottom, "-": Right/Top
                                         Separate multiple Arrows by NaN-Pairs
                                         #default: 'arrow'

 LineStyle    '-' '--' ':' '-.' 'none'   LineStyle of ArrowEdge
                                         #default: 'none'

 LineWidth     [ 1  1 ]  numeric         LineWidth of ArrowEdge
                                         #default:   1

 EdgeColor     [ 1  3 ]  numeric         LineColor of ArrowEdge
              'none' '#colspecX#'        #default: 'k'

 FaceColor     [ 1  3 ]  numeric         Color of Arrow
              'none' '#colspecX#'        #default: 'w'

 Number_       [ 1  1 ]  uint8           Number of Arrows along XY-Line
                                          0: No Arrows
                                         Number+10*SplinePotenz*i calculates a Spline along XY-Line
                                         #default:   1+10*i

 Resolution_   [ 1  1 ]  uint8           Resolution of single Arrow
                                         #default:   100

 Shape_        [ 1  -5 ]  numeric        Shape of Arrow by ARROWS
                                          [ BandWidth  HeadLength  HeadWidth  HeadFak  PikeMode ]
                                          BW, HL, HW are normalized to Length of Arrow
                                          A NonZero imaginary Part for BW, HL, HW use absolute Units
                                         #default: []

 Offset_       [ 1  -2 ]  numeric        Offset at begin and End of XY-Line
                                         #default: []

 Length_       [ 1  - ]  numeric         Length of Arrows, single or Number Elements
                                         #default: []

 Distance_     [ 1  - ]  numeric         Distance between Arrows, single or Number-1 Elements
                                         #default: []


DOWNLOAD M-File ^
138 KByte
CROSS-REFERENCE INFORMATION ^
This function calls:
This function is called by:
TOPOSURF Visualisation of topological Surfaces/Images
SUBFUNCTIONS ^
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 


Generated on Sat 09-May-2009 10:46:59 by m2html © 2003, Revision by Ch.Begler 2008
^