annotate scripts/image/im2frame.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29359
diff changeset
3 ## Copyright (C) 2014-2022 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/>.
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
7 ##
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
8 ## This file is part of Octave.
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
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: 23220
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: 22627
diff changeset
13 ## (at your option) any later version.
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
14 ##
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22627
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22627
diff changeset
18 ## GNU General Public License for more details.
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
19 ##
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
20 ## You should have received a copy of the GNU General Public License
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
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: 23220
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 ########################################################################
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
25
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {@var{frame} =} im2frame (@var{rgb})
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
28 ## @deftypefnx {} {@var{frame} =} im2frame (@var{x}, @var{map})
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
29 ## Convert image to movie frame.
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
30 ##
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
31 ## A movie frame is simply a struct with the fields @qcode{"cdata"} and
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
32 ## @qcode{"colormap"}.
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
33 ##
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
34 ## Support for N-dimensional images is given when each image projection,
20173
777f26aa8e3e doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
35 ## matrix sizes of @nospell{MxN and MxNx3} for RGB images, is concatenated
777f26aa8e3e doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
36 ## along the fourth dimension. In such cases, the returned value is a struct
777f26aa8e3e doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
37 ## array.
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
38 ##
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
39 ## @seealso{frame2im}
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
40 ## @end deftypefn
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
41
22959
8defe99c9650 Move frame2im and im2frame to image/ directory (bug #49939).
Rik <rik@octave.org>
parents: 22627
diff changeset
42 function frame = im2frame (x, map = [])
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
43
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27978
diff changeset
44 if (nargin < 1)
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
45 print_usage ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
46 elseif (ndims (x) > 4)
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
47 error ("im2frame: X and RGB must be a single image");
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
48 endif
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
49
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
50 ## Matlab documentation is incorrect. Singleton 3rd dimension will error
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
51 ## without cmap (no use of default cmap), and cmap is added to the frame
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
52 ## even when image is RGB.
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
53
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
54 nchannels = size (x, 3);
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
55 if (nchannels == 3)
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
56 ## RGB image, do nothing
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
57 elseif (nchannels == 1)
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
58 if (nargin < 2)
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
59 error ("im2frame: MAP required for indexed images");
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
60 endif
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
61 [x, map] = ind2x ("im2frame", x, map);
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
62 else
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
63 error ("im2frame: first argument must be indexed or RGB image");
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
64 endif
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
65
22959
8defe99c9650 Move frame2im and im2frame to image/ directory (bug #49939).
Rik <rik@octave.org>
parents: 22627
diff changeset
66 ## support N-dimensional images and return a struct array
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
67 if (ndims (x) == 4)
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
68 x = reshape (num2cell (x, [1 2 3]), 1, size (x, 4));
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
69 endif
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
70
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
71 frame = struct ("cdata", x, "colormap", map);
21758
ffad2baa90f7 maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents: 20852
diff changeset
72
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
73 endfunction
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
74
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
75
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
76 %!function f = make_rgb_f ()
22627
7b190a2f11cb maint: Use 2-space indent in definition of BIST %!functions.
Rik <rik@octave.org>
parents: 22323
diff changeset
77 %! f = randi ([0 255], 10, 20, 3);
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
78 %!endfunction
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
79
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
80 %!function f = make_ind_f ()
22959
8defe99c9650 Move frame2im and im2frame to image/ directory (bug #49939).
Rik <rik@octave.org>
parents: 22627
diff changeset
81 %! f = randi ([1 100], 10, 20, 1);
19313
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
82 %!endfunction
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
83
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
84 %!test
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
85 %! rgb = make_rgb_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
86 %! assert (im2frame (rgb), struct ("cdata", rgb, "colormap", []));
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
87
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
88 %!test
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
89 %! ind = make_ind_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
90 %! cmap = bone (100);
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
91 %! assert (im2frame (ind, cmap), struct ("cdata", ind, "colormap", cmap));
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
92
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
93 %!test
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
94 %! rgb1 = make_rgb_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
95 %! rgb2 = make_rgb_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
96 %! rgb3 = make_rgb_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
97 %! rgb4 = make_rgb_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
98 %! assert (im2frame (cat (4, rgb1, rgb2, rgb3, rgb4)),
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
99 %! struct ("cdata", {rgb1, rgb2, rgb3, rgb4}, "colormap", []));
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
100
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
101 %!test
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
102 %! ind1 = make_ind_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
103 %! ind2 = make_ind_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
104 %! ind3 = make_ind_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
105 %! ind4 = make_ind_f ();
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
106 %! cmap = bone (100);
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
107 %! assert (im2frame (cat (4, ind1, ind2, ind3, ind4), cmap),
39a69f54417e New functions im2frame and frame2im.
Carnë Draug <carandraug@octave.org>
parents:
diff changeset
108 %! struct ("cdata", {ind1, ind2, ind3, ind4}, "colormap", cmap));