Mercurial > octave
annotate scripts/plot/draw/scatter3.m @ 32074:03fe0b635d2e
quiver/quiver3: Overhaul input processing, validation, and add BISTs.
* scripts/plot/draw/private/__quiver__.m: Overhaul numeric input validation.
Simplify input classification using numeric input count switch statements
and avoid quiver3 miscount due to scale factor. Add error messages for all
valid numeric input combinations including vector x,y,z and scale factor.
Move newplot command from quiver/quiver3 into __quiver__ after numeric input
validation. Add hax as an output argument to return any changes back to
calling function.
* scripts/plot/draw/quiver.m: Remove newplot call. Update __quiver__ call
to include hax as a return variable. Update docstring with note that line
style and name-value pairs can both be provided but linstyle must appear
first. Add BISTs to check standard inputs with single and multiple arrows,
arrowhead shape, vector and array inputs, proper treatment of scaling factor
"off", some simple input styles, and input validation BISTs to cover all
numeric input errors. Added known failing BIST for linestyle+pair
arrowhead showing when it should stay off (bug #64143).
* scripts/plot/draw/quiver3.m: Remove newplot call. Update __quiver__ call
to include hax as a return variable. Update docstring with note that line
style and name-value pairs can both be provided but linstyle must appear
first. Add BISTs to check standard inputs with single and multiple arrows,
vector and array inputs, and input validation BISTs to cover all numeric
input errors.
* etc/NEWS.9.md: Update quiver/quiver3 improvement description under General
Improvements.
author | Nicholas R. Jankowski <jankowski.nicholas@gmail.com> |
---|---|
date | Wed, 03 May 2023 22:52:33 -0400 |
parents | 597f3ee61a48 |
children | 2e484f9f1f18 |
rev | line source |
---|---|
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
1 ######################################################################## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
2 ## |
31706
597f3ee61a48
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
30564
diff
changeset
|
3 ## Copyright (C) 2007-2023 The Octave Project Developers |
27918
b442ec6dda5c
use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents:
26376
diff
changeset
|
4 ## |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
5 ## See the file COPYRIGHT.md in the top-level directory of this |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
6 ## distribution or <https://octave.org/copyright/>. |
7189 | 7 ## |
8 ## This file is part of Octave. | |
9 ## | |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
24432
diff
changeset
|
10 ## Octave is free software: you can redistribute it and/or modify it |
7189 | 11 ## under the terms of the GNU General Public License as published by |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
24432
diff
changeset
|
12 ## the Free Software Foundation, either version 3 of the License, or |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22367
diff
changeset
|
13 ## (at your option) any later version. |
7189 | 14 ## |
15 ## Octave is distributed in the hope that it will be useful, but | |
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of | |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22367
diff
changeset
|
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22367
diff
changeset
|
18 ## GNU General Public License for more details. |
7189 | 19 ## |
20 ## You should have received a copy of the GNU General Public License | |
21 ## along with Octave; see the file COPYING. If not, see | |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
24432
diff
changeset
|
22 ## <https://www.gnu.org/licenses/>. |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
23 ## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
24 ######################################################################## |
7189 | 25 |
26 ## -*- texinfo -*- | |
20852
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
27 ## @deftypefn {} {} scatter3 (@var{x}, @var{y}, @var{z}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
28 ## @deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
29 ## @deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
30 ## @deftypefnx {} {} scatter3 (@dots{}, @var{style}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
31 ## @deftypefnx {} {} scatter3 (@dots{}, "filled") |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
32 ## @deftypefnx {} {} scatter3 (@dots{}, @var{prop}, @var{val}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
33 ## @deftypefnx {} {} scatter3 (@var{hax}, @dots{}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
34 ## @deftypefnx {} {@var{h} =} scatter3 (@dots{}) |
17122
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
35 ## Draw a 3-D scatter plot. |
7189 | 36 ## |
17122
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
37 ## A marker is plotted at each point defined by the coordinates in the vectors |
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
38 ## @var{x}, @var{y}, and @var{z}. |
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
39 ## |
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
40 ## The size of the markers is determined by @var{s}, which can be a scalar |
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
41 ## or a vector of the same length as @var{x}, @var{y}, and @var{z}. If @var{s} |
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
42 ## is not given, or is an empty matrix, then a default value of 8 points is |
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
43 ## used. |
7189 | 44 ## |
45 ## The color of the markers is determined by @var{c}, which can be a string | |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11563
diff
changeset
|
46 ## defining a fixed color; a 3-element vector giving the red, green, and blue |
11563
3c6e8aaa9555
Grammarcheck m-files before 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
47 ## components of the color; a vector of the same length as @var{x} that gives |
21546
f7f97d7e9294
doc: Wrap m-file docstrings to 79 characters + newline (80 total).
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
48 ## a scaled index into the current colormap; or an @nospell{Nx3} matrix |
f7f97d7e9294
doc: Wrap m-file docstrings to 79 characters + newline (80 total).
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
49 ## defining the RGB color of each marker individually. |
7189 | 50 ## |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11563
diff
changeset
|
51 ## The marker to use can be changed with the @var{style} argument, that is a |
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11563
diff
changeset
|
52 ## string defining a marker in the same manner as the @code{plot} command. |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17211
diff
changeset
|
53 ## If no marker is specified it defaults to @qcode{"o"} or circles. |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17211
diff
changeset
|
54 ## If the argument @qcode{"filled"} is given then the markers are filled. |
17122
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
55 ## |
24431
0c6cedafc71e
doc: Use 'axes' rather than 'axis' appropriately in docstrings.
Rik <rik@octave.org>
parents:
23219
diff
changeset
|
56 ## If the first argument @var{hax} is an axes handle, then plot into this axes, |
17122
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
57 ## rather than the current axes returned by @code{gca}. |
7189 | 58 ## |
28286
496735a910c1
Add graphics object "scatter" (bug #58282).
Markus Mützel <markus.muetzel@gmx.de>
parents:
27923
diff
changeset
|
59 ## The optional return value @var{h} is a graphics handle to the scatter |
14001
5f0bb45e615c
doc: Update documentation for functions returning a graphics handle h (Bug #34761)
Rik <octave@nomad.inbox5.com>
parents:
12320
diff
changeset
|
60 ## object representing the points. |
7189 | 61 ## |
62 ## @example | |
63 ## @group | |
64 ## [x, y, z] = peaks (20); | |
65 ## scatter3 (x(:), y(:), z(:), [], z(:)); | |
66 ## @end group | |
67 ## @end example | |
68 ## | |
28286
496735a910c1
Add graphics object "scatter" (bug #58282).
Markus Mützel <markus.muetzel@gmx.de>
parents:
27923
diff
changeset
|
69 ## Programming Note: The full list of properties is documented at |
496735a910c1
Add graphics object "scatter" (bug #58282).
Markus Mützel <markus.muetzel@gmx.de>
parents:
27923
diff
changeset
|
70 ## @ref{Scatter Properties}. |
17122
eaab03308c0b
doc: Rewrite docstrings for most plot functions.
Rik <rik@octave.org>
parents:
17069
diff
changeset
|
71 ## @seealso{scatter, patch, plot} |
7189 | 72 ## @end deftypefn |
73 | |
24819
bdec5e695ec3
scatter3.m, surf.m: Match output variable name to documentation.
Rik <rik@octave.org>
parents:
24534
diff
changeset
|
74 function h = scatter3 (varargin) |
7189 | 75 |
17069
1cbdd14711c5
scatter3.m, scatter.m: Update to use new __plt_get_axis_arg__.
Pantxo Diribarne <pantxo.diribarne@gmail.com>
parents:
14359
diff
changeset
|
76 [hax, varargin, nargin] = __plt_get_axis_arg__ ("scatter3", varargin{:}); |
7215 | 77 |
7189 | 78 if (nargin < 2) |
79 print_usage (); | |
17404
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
80 endif |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
81 |
17211
87ba70043bfc
Don't use ifelse in plot fcns to avoid unnecessary fcn evaluations.
Rik <rik@octave.org>
parents:
17190
diff
changeset
|
82 oldfig = []; |
17301
68bcac3c043a
Correct inversion accidentally introduced in cset 87ba70043bfc.
Rik <rik@octave.org>
parents:
17281
diff
changeset
|
83 if (! isempty (hax)) |
17211
87ba70043bfc
Don't use ifelse in plot fcns to avoid unnecessary fcn evaluations.
Rik <rik@octave.org>
parents:
17190
diff
changeset
|
84 oldfig = get (0, "currentfigure"); |
87ba70043bfc
Don't use ifelse in plot fcns to avoid unnecessary fcn evaluations.
Rik <rik@octave.org>
parents:
17190
diff
changeset
|
85 endif |
17404
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
86 unwind_protect |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
87 hax = newplot (hax); |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
88 |
17404
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
89 htmp = __scatter__ (hax, 3, "scatter3", varargin{:}); |
17126
26589abbc78d
Don't pass axis handle unnecessarily from high level to low level plot functions.
Rik <rik@octave.org>
parents:
17122
diff
changeset
|
90 |
22367
459545bc9019
Use ishold () rather than ishold (hax) for performance.
Rik <rik@octave.org>
parents:
22351
diff
changeset
|
91 if (! ishold ()) |
22351
e6df1ddfc3cf
Change DefaultAxesBox property to "off".
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
92 set (hax, "view", [-37.5, 30], |
17404
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
93 "xgrid", "on", "ygrid", "on", "zgrid", "on"); |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
94 endif |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
95 unwind_protect_cleanup |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
96 if (! isempty (oldfig)) |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
97 set (0, "currentfigure", oldfig); |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
98 endif |
5e552cd9315a
Overhaul scatter family of functions
Rik <rik@octave.org>
parents:
17301
diff
changeset
|
99 end_unwind_protect |
7189 | 100 |
101 if (nargout > 0) | |
24819
bdec5e695ec3
scatter3.m, surf.m: Match output variable name to documentation.
Rik <rik@octave.org>
parents:
24534
diff
changeset
|
102 h = htmp; |
7189 | 103 endif |
104 | |
105 endfunction | |
7245 | 106 |
11363
a0dfd7e8e3e2
Assign data used in demo plots for reproducibility between runs
Rik <octave@nomad.inbox5.com>
parents:
10793
diff
changeset
|
107 |
7245 | 108 %!demo |
14237
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
109 %! clf; |
7245 | 110 %! [x, y, z] = peaks (20); |
111 %! scatter3 (x(:), y(:), z(:), [], z(:)); | |
22302
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
112 %! title ({"Default scatter3() plot", ... |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
113 %! "constant size bubbles and color determined by Z"}); |
9295
10b9a71a81f1
__scatter__.m: If the color spec is empty, set using __next_line_color__.
Ben Abbott <bpabbott@mac.com>
parents:
9245
diff
changeset
|
114 |
10b9a71a81f1
__scatter__.m: If the color spec is empty, set using __next_line_color__.
Ben Abbott <bpabbott@mac.com>
parents:
9245
diff
changeset
|
115 %!demo |
14237
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
116 %! clf; |
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
117 %! x = rand (20,1); y = rand (20,1); z = rand (20,1); |
22302
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
118 %! scatter3 (x(:), y(:), z(:), 10, z(:), "s"); |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
119 %! title ({"scatter3() plot", ... |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
120 %! "marker is square, size is 10, color determined by Z"}); |
9295
10b9a71a81f1
__scatter__.m: If the color spec is empty, set using __next_line_color__.
Ben Abbott <bpabbott@mac.com>
parents:
9245
diff
changeset
|
121 |
10b9a71a81f1
__scatter__.m: If the color spec is empty, set using __next_line_color__.
Ben Abbott <bpabbott@mac.com>
parents:
9245
diff
changeset
|
122 %!demo |
14237
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
123 %! clf; |
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
124 %! x = rand (20,1); y = rand (20,1); z = rand (20,1); |
22302
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
125 %! scatter3 (x(:), y(:), z(:), 20*z(:), [], "s"); |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
126 %! title ({"scatter3() plot", ... |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
127 %! "marker is square, size is determined by Z"}); |
9295
10b9a71a81f1
__scatter__.m: If the color spec is empty, set using __next_line_color__.
Ben Abbott <bpabbott@mac.com>
parents:
9245
diff
changeset
|
128 |
10b9a71a81f1
__scatter__.m: If the color spec is empty, set using __next_line_color__.
Ben Abbott <bpabbott@mac.com>
parents:
9245
diff
changeset
|
129 %!demo |
14237
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
130 %! clf; |
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
131 %! x = rand (20,1); y = rand (20,1); z = rand (20,1); |
22302
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
132 %! scatter3 (x(:), y(:), z(:), 20*z(:), z(:), "s"); |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
133 %! title ({"scatter3() plot", ... |
1c4cd12987f5
Use Octave syntax in graphics demos.
Rik <rik@octave.org>
parents:
21546
diff
changeset
|
134 %! "marker is square, size and color determined by Z"}); |