Documentation

Contour Properties

Contour chart appearance and behavior

expand all in page

Contourproperties control the appearance and behavior ofContour对象。通过改变属性值,您可以修改fy certain aspects of the contour chart.

Starting in R2014b, you can use dot notation to query and set properties.

[C,h] = contour(...); w = h.LineWidth; h.LineWidth = 2;

If you are using an earlier release, use thegetandsetfunctions instead.

Levels

expand all

Contour levels, specified as a vector of z values. By default, thecontourfunction chooses values that span the range of values in theZDataproperty.

Setting this property sets the associated mode property to manual.

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Selection mode for theLevelList, specified as one of these values:

  • 'auto'— Determine the values based on theZDatavalues.

  • 'manual'— Use manually specified values. To specify the values, set theLevelListproperty. When the mode is manual, thecontourfunction does not change the values as you changeZData.

Spacing between contour lines, specified as a scalar numeric value. For example, specify a value of 2 to draw contour lines at increments of 2. Thecontourfunction determines the contour interval based on theZDatavalues.

Setting this property sets the associated mode property to manual.

Example:3.4

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Selection mode for theLevelStep, specified as one of these values:

  • 'auto'— Determine the value based on theZDatavalues.

  • 'manual'— Use a manually specified value. To specify the value, set theLevelStepproperty. When the mode is manual, thecontourfunction does not change the value as you changeZData.

颜色和样式

expand all

Fill between contour lines, specified as one of these values:

  • 'off'— Do not fill the spaces between contour lines with a color. This is the default value when you create the contour chart using thecontourorcontour3functions.

  • 'on'— Fill the spaces between contour lines with color. This is the default value when you create the contour chart using thecontourffunction.

Color of contour lines, specified as'flat', an RGB triplet, or one of the color options listed in the table.

  • To use a different color for each contour line, specify'flat'. The colors are determined by the contour value of the line, the colormap, and the scaling of data values into the colormap. For more information on color scaling, seecaxis.

  • To use the same color for all contour lines, specify an RGB triplet or one of the color options listed in the table.

为一个自定义颜色,指定一个RGB值。RGBtriplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range[0,1]; for example,[0.4 0.6 0.7]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

Option Description Equivalent RGB Triplet
'red'or'r' Red [1 0 0]
'green'or'g' Green [0 1 0]
'blue'or'b' Blue [0 0 1]
'yellow'or'y' Yellow [1 1 0]
'magenta'or'm' Magenta [1 0 1]
'cyan'or'c' Cyan [0 1 1]
'white'or'w' White [1 1 1]
'black'or'k' Black [0 0 0]
'none' No color Not applicable

Line style, specified as one of the options listed in this table.

Line Style Description Resulting Line
“- - -” Solid line

'--' Dashed line

':' Dotted line

'-.' Dash-dotted line

'none' No line No line

Width of contour lines, specified as a positive value in points. One point equals 1/72 inch.

Example:2

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Labels

expand all

Contour line labels, specified as one of these values:

  • 'off'— Do not label the contour lines.

  • 'on'— Display text labels on each contour line indicating the contour value.

Spacing between contour line labels, specified as a numeric scalar in point units. One point equals 1/72 inch. You must set theShowTextproperty to'on'for theLabelSpacingproperty to have an effect.

If you use theclabelfunction to display the labels, then theLabelSpacingproperty has no effect. The contour plot contains a single label per line instead.

Example:36

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Interval between labeled contour lines, specified as a scalar numeric value. By default, the contour plot includes a label for every contour line when theShowTextproperty is set to'on'.

Setting this property sets the associated mode property to manual.

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Selection mode for theTextStep, specified as one of these values:

  • 'auto'— Determine value based on theZDatavalues. If theShowTextproperty is set to'on', then thecontourfunction labels every contour line.

  • 'manual'— Use a manually specified value. To specify the value, set theTextStepproperty.

Contour lines to label, specified as a vector of real values.

Setting this property sets the associated mode property to manual.

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Selection mode for theTextList, specified as one of these values:

  • 'auto'— Use values equal to the values of theLevelListproperty. The contour plot includes a text label for each line.

  • 'manual'— Use manually specified values. Specify the values by setting theTextListproperty.

Data

expand all

This property is read-only.

轮廓线definitions, returned as a two-row matrix. Each contour line in the plot has an associated definition. If there are a total ofNcontour lines in the plot, then the contour matrix consists ofNdefinitions:

C = [C(1) C(2)...C(k)...C(N)]
Each contour line definition follows this pattern:
C(k) = [level x(1) x(2)... numxy y(1) y(2)... ]
The first entry,level, indicates the contour level where the contour line is drawn. Beneath the contour level is the number of (x,y) vertices that define the contour line. The remaining columns contain the data for each of the vertices. If the first and last vertices are the same, then the contour line is a closed loop. If a particular contour level has multiple contour lines in the graph, then the matrix contains a separate definition for each line.

Example

Create a contour plot of values from thepeaksfunction.

[X,Y,Z] = peaks(3); [C,h] = contour(X,Y,Z);

Access the contour matrix using either the output argumentCor theContourMatrixproperty of theContourobject (h.ContourMatrix). The contour matrix contains definitions for each of the seven contour lines. The circles in this matrix show the beginnings of the contour line definitions.

The first definition in the matrix indicates that there is a contour line drawn at the -0.2 level , consisting of the three vertices(-0.5504,-3),(0,-2.89), and(0.5506,-3). Since the first and last vertices are not the same, the contour line is not a closed loop. The last definition indicates that there is a closed loop at the 0.8 level.

xvalues, specified as a vector or matrix.

  • IfXDatais a vector, thenlength(XData)must equalsize(ZData,2)andYDatamust also be a vector. TheXDatavalues must be strictly increasing or strictly decreasing and cannot contain any duplicates.

  • IfXDatais a matrix, thensize(XData)andsize(YData)must equalsize(ZData). Typically, you should set theXDatavalues so that the columns are strictly increasing or strictly decreasing and the rows are uniform (or the rows are strictly increasing or strictly decreasing and the columns are uniform).

Setting this property sets the associated mode property to manual.

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64|logical

Selection mode for theXData, specified as one of these values:

  • 'auto'— Set theXDatausing the column indices ofZData.

  • 'manual'— Use manually specified values. To specify the values, set theXDataproperty directly, or specify the input argumentXto thecontour,contourf, orcontour3function.

Variable linked toXData, specified as a character vector or string containing a MATLAB®workspace variable name. MATLAB evaluates the variable in the base workspace to generate theXData.

By default, there is no linked variable so the value is an empty character vector,''. If you link a variable, then MATLAB does not update theXDatavalues immediately. To force an update of the data values, use therefreshdatafunction.

Note

If you change one data source property to a variable that contains data of a different dimension, you might cause the function to generate a warning and not render the graph until you have changed all data source properties to appropriate values.

Example:'x'

yvalues, specified as a vector or matrix.

  • IfYDatais a vector, thenlength(YData)must equalsize(ZData,1)andXDatamust also be a vector. TheXDatavalues must be strictly increasing or strictly decreasing and cannot contain any duplicates.

  • IfYDatais a matrix, thensize(XData)andsize(YData)must equalsize(ZData). Typically, you should set theYDatavalues so that the columns are strictly increasing or strictly decreasing and the rows are uniform (or the rows are strictly increasing or strictly decreasing and the columns are uniform).

Setting this property sets the associated mode property to manual.

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64|logical

Selection mode for theYData, specified as one of these values:

  • 'auto'— Set theYDatausing the row indices ofZData.

  • 'manual'— Use manually specified values. To specify the values, set theYDataproperty directly, or specify the input argumentYto thecontour,contourf, orcontour3function.

Variable linked toYData, specified as a character vector or string containing a MATLAB workspace variable name. MATLAB evaluates the variable in the base workspace to generate theYData.

By default, there is no linked variable so the value is an empty character vector,''. If you link a variable, then MATLAB does not update theYDatavalues immediately. To force an update of the data values, use therefreshdatafunction.

Note

If you change one data source property to a variable that contains data of a different dimension, you might cause the function to generate a warning and not render the graph until you have changed all data source properties to appropriate values.

Example:'y'

Data that defines the surface to contour, specified as a matrix.ZDatamust be at least a 2-by-2 matrix.

Setting this property sets the associated mode property to manual.

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Variable linked toZData, specified as a character vector or string containing a MATLAB workspace variable name. MATLAB evaluates the variable in the base workspace to generate theZData.

By default, there is no linked variable so the value is an empty character vector,''. If you link a variable, then MATLAB does not update theZDatavalues immediately. To force an update of the data values, use therefreshdatafunction.

Note

If you change one data source property to a variable that contains data of a different dimension, you might cause the function to generate a warning and not render the graph until you have changed all data source properties to appropriate values.

Example:'z'

Legend

expand all

Legend label, specified as a character vector or string. If you do not specify the text, then the legend uses a label of the form'dataN'. The legend does not display until you call thelegendcommand.

Example:'Label Text'

Data Types:char|string

This property is read-only.

Control for including or excluding the object from a legend, returned as anAnnotationobject. Set the underlyingIconDisplayStyleproperty to one of these values:

  • 'on'— Include the object in the legend (default).

  • 'off'— Do not include the object in the legend.

For example, exclude a stem chart from the legend.

p = plot(1:10,'DisplayName','Line Chart'); holdons = stem(1:10,'DisplayName','Stem Chart'); holdoffs.Annotation.LegendInformation.IconDisplayStyle ='off'; legend('show')

Alternatively, you can control the items in a legend using thelegendfunction. Specify the first input argument as a vector of the graphics objects to include.

p = plot(1:10,'DisplayName','Line Chart'); holdons = stem(1:10,'DisplayName','Stem Chart'); holdofflegend(p)

Interactivity

expand all

State of visibility, specified as one of these values:

  • 'on'— Display the object.

  • 'off'— Hide the object without deleting it. You still can access the properties of an invisible object.

Context menu, specified as aContextMenuobject. Use this property to display a context menu when you right-click the object. Create the context menu using theuicontextmenufunction.

Note

If thePickablePartsproperty is set to'none'or if theHitTestproperty is set to'off', then the context menu does not appear.

Selection state, specified as one of these values:

  • 'on'— Selected. If you click the object when in plot edit mode, then MATLAB sets itsSelectedproperty to'on'. If theSelectionHighlightproperty also is set to'on', then MATLAB displays selection handles around the object.

  • 'off'— Not selected.

Display of selection handles when selected, specified as one of these values:

  • 'on'— Display selection handles when theSelectedproperty is set to'on'.

  • 'off'— Never display selection handles, even when theSelectedproperty is set to'on'.

Clipping of the object to the axes limits, specified as one of these values:

  • 'on'— Do not display parts of the object that are outside the axes limits.

  • 'off'——显示整个对象,即使它的一部分ppear outside the axes limits. Parts of the object might appear outside the axes limits if you create a plot, sethold on, freeze the axis scaling, and then create the object so that it is larger than the original plot.

TheClippingproperty of the axes that contains the object must be set to'on'. Otherwise, this property has no effect. For more information about the clipping behavior, see theClippingproperty of the axes.

Callbacks

expand all

Mouse-click callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you click the object. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • Clicked object — Access properties of the clicked object from within the callback function.

  • Event data — Empty argument. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, seeCallback Definition.

Note

If thePickablePartsproperty is set to'none'or if theHitTestproperty is set to'off', then this callback does not execute.

Creation callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you create the object. MATLAB executes the callback after creating the object and setting all of its properties. Setting theCreateFcnproperty on an existing object has no effect. To have an effect, you must specify theCreateFcnproperty during object creation. One way to specify the property during object creation is to set the default property value for the object. SeeDefault Property Valuesfor more information.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • Created object — Access properties of the object from within the callback function. You also can access the object through theCallbackObjectproperty of the root, which can be queried using thegcbofunction.

  • Event data — Empty argument. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, seeCallback Definition.

Deletion callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you delete the object MATLAB executes the callback before destroying the object so that the callback can access its property values.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • Deleted object — Access properties of the object from within the callback function. You also can access the object through theCallbackObjectproperty of the root, which can be queried using thegcbofunction.

  • Event data — Empty argument. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, seeCallback Definition.

Callback Execution Control

expand all

Callback interruption, specified as'on'or'off'. TheInterruptibleproperty determines if a running callback can be interrupted.

Note

Consider these callback states where:

  • Therunningcallback is the currently executing callback.

  • Theinterruptingcallback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. TheInterruptibleproperty of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then theBusyActionproperty of the object owning the interrupting callback determines if it is discarded or put in the queue.

TheInterruptibleproperty determines if another callback can interrupt theButtonDownFcncallback of theContourobject. TheInterruptibleproperty has two values:

  • 'on'— Interruptible. Interruption occurs at the next point where MATLAB processes the queue. For example, when you have a command such asdrawnow,figure,getframe,waitfor, orpause.

    • If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes. For more information, seeInterrupt Callback Execution.

    • If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

  • 'off'— Not interruptible. MATLAB finishes executing the running callback without any interruptions.

Callback queuing specified as'queue'or'cancel'. TheBusyActionproperty determines how MATLAB handles the execution of interrupting callbacks.

Consider these callback states where:

  • Therunningcallback is the currently executing callback.

  • Theinterruptingcallback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. TheInterruptibleproperty of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then theBusyActionproperty of the object owning the interrupting callback determines if it is discarded or put in the queue.

If a callback of theContourobject tries to interrupt a running callback that cannot be interrupted, then theBusyActionproperty determines if it is discarded or put in the queue. Specify theBusyActionproperty as one of these values:

  • 'queue'— Put the interrupting callback in a queue to be processed after the running callback finishes execution. (default behavior)

  • 'cancel'— Discard the interrupting callback.

Ability to capture mouse clicks, specified as one of these values:

  • 'visible'— Capture mouse clicks only when visible. TheVisibleproperty must be set to'on'. TheHitTestproperty determines if theContourobject responds to the click or if an ancestor does.

  • 'none'— Cannot capture mouse clicks. Clicking theContourobject passes the click to the object behind it in the current view of the figure window. TheHitTestproperty of theContourobject has no effect.

Response to captured mouse clicks, specified as one of these values:

  • 'on'— Trigger theButtonDownFcncallback of theContourobject. If you have defined theUIContextMenuproperty, then invoke the context menu.

  • 'off'— Trigger the callbacks for the nearest ancestor of theContourobject that has:

    • HitTestproperty set to'on'

    • PickablePartsproperty set to a value that enables the ancestor to capture mouse clicks.

Note

ThePickablePartsproperty determines if theContourobject can capture mouse clicks. If it cannot, then theHitTestproperty has no effect.

This property is read-only.

Deletion status, returned as'off'or'on'. MATLAB sets theBeingDeletedproperty to'on'when the delete function of the object begins execution (see theDeleteFcnproperty). TheBeingDeletedproperty remains set to'on'until the object no longer exists.

Check the value of theBeingDeletedproperty if you need to verify that the object is not about to be deleted before querying or modifying it.

Parent/Child

expand all

Parent, specified as anAxes,Group, orTransformobject.

The object has no children. You cannot set this property.

Visibility of the object handle in theChildrenproperty of the parent, specified as one of these values:

  • 'on'— Object handle is always visible.

  • 'off'— Object handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. Set theHandleVisibilityto'off'to temporarily hide the handle during the execution of that function.

  • 'callback'— Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command line, but permits callback functions to access it.

If the object is not listed in theChildrenproperty of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. For example, when you have a function such asget,findobj,gca,gcf,gco,newplot,cla,clf, andclose.

Hidden object handles are still valid. Set the rootShowHiddenHandlesproperty to'on'to list all object handles regardless of theirHandleVisibilityproperty setting.

Identifiers

expand all

This property is read-only.

Type of graphics object, returned as'contour'.

Tag to associate with thecontourobject, specified as a character vector or string scalar.

Use this property to findcontourobjects in a hierarchy. For example, you can use thefindobjfunction to findcontourobjects that have a specificTagproperty value.

Example:'January Data'

User data to associate with thecontourobject, specified as any MATLAB data, for example, a scalar, vector, matrix, cell array, character array, table, or structure. MATLAB does not use this data.

To associate multiple sets of data or to attach a field name to the data, use thegetappdataandsetappdatafunctions.

Example:1:100

See Also

||||

Topics

Introduced before R2006a

Was this topic helpful?
MATLAB Documentation
万博1manbetx

Try MATLAB, Simulink, and Other Products

Get trial now