octave_packages/geometry-1.5.0/geom2d/createLine.m

   1 %% Copyright (c) 2011, INRA
   2 %% 2003-2011, David Legland <david.legland@grignon.inra.fr>
   3 %% 2011 Adapted to Octave by Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
   4 %%
   5 %% All rights reserved.
   6 %% (simplified BSD License)
   7 %%
   8 %% Redistribution and use in source and binary forms, with or without
   9 %% modification, are permitted provided that the following conditions are met:
  10 %%
  11 %% 1. Redistributions of source code must retain the above copyright notice, this
  12 %%    list of conditions and the following disclaimer.
  13 %%
  14 %% 2. Redistributions in binary form must reproduce the above copyright notice,
  15 %%    this list of conditions and the following disclaimer in the documentation
  16 %%    and/or other materials provided with the distribution.
  17 %%
  18 %% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19 %% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 %% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 %% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  22 %% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 %% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 %% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 %% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 %% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 %% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 %% POSSIBILITY OF SUCH DAMAGE.
  29 %%
  30 %% The views and conclusions contained in the software and documentation are
  31 %% those of the authors and should not be interpreted as representing official
  32 %% policies, either expressed or implied, of copyright holder.
  33
  34 %% -*- texinfo -*-
  35 %% @deftypefn {Function File} {@var{line} =} createLine(varargin)
  36 %% Create a straight line from 2 points, or from other inputs
  37 %%
  38 %%   Line is represented in a parametric form : [x0 y0 dx dy]
  39 %%   x = x0 + t*dx
  40 %%   y = y0 + t*dy;
  41 %%
  42 %%
  43 %%   L = createLine(p1, p2);
  44 %%   Returns the line going through the two given points.
  45 %%
  46 %%   L = createLine(x0, y0, dx, dy);
  47 %%   Returns the line going through point (x0, y0) and with direction
  48 %%   vector(dx, dy).
  49 %%
  50 %%   L = createLine(LINE);
  51 %%   where LINE is an array of 4 values, creates the line going through the
  52 %%   point (LINE(1) LINE(2)), and with direction given by vector (LINE(3)
  53 %%   LINE(4)).
  54 %%
  55 %%   L = createLine(THETA);
  56 %%   Create a polar line originated at (0,0) and with angle THETA.
  57 %%
  58 %%   L = createLine(RHO, THETA);
  59 %%   Create a polar line with normal theta, and with min distance to origin
  60 %%   equal to rho. rho can be negative, in this case, the line is the same
  61 %%   as with CREATELINE(-rho, theta+pi), but the orientation is different.
  62 %%
  63 %%
  64 %%   Note: in all cases, parameters can be vertical arrays of the same
  65 %%   dimension. The result is then an array of lines, of dimensions [N*4].
  66 %%
  67 %%   NOTE : A line can also be represented with a 1*5 array :
  68 %%   [x0 y0 dx dy t].
  69 %%   whith 't' being one of the following :
  70 %%   - t=0 : line is a singleton (x0,y0)
  71 %%   - t=1 : line is an edge segment, between points (x0,y0) and (x0+dx,
  72 %%   y0+dy).
  73 %%   - t=Inf : line is a Ray, originated from (x0,y0) and going to infinity
  74 %%   in the direction(dx,dy).
  75 %%   - t=-Inf : line is a Ray, originated from (x0,y0) and going to infinity
  76 %%   in the direction(-dx,-dy).
  77 %%   - t=NaN : line is a real straight line, and contains all points
  78 %%   verifying the above equation.
  79 %%   This seems us a convenient way to represent uniformly all kind of lines
  80 %%   (including edges, rays, and even point).
  81 %%
  82 %%   NOTE2 : Any line object can be represented using a 1x6 array :
  83 %%   [x0 y0 dx dy t0 t1]
  84 %%   the first 4 parameters define the supporting line,
  85 %%   t0 represent the position of the first point on the line,
  86 %%   and t1 the position of the last point.
  87 %%   * for edges : t0 = 0, and t1=1
  88 %%   * for straight lines : t0 = -inf, t1=inf
  89 %%   * for rays : t0=0, t1=inf (or t0=-inf,t1=0 for inverted ray).
  90 %%   I propose to call these objects 'lineArc'
  91 %%
  92 %% @seealso{lines2d, createEdge, createRay}
  93 %% @end deftypefn
  94
  95 function line = createLine(varargin)
  96
  97   if length(varargin)==1
  98       % Only one input parameter. It can be :
  99       % - line angle
 100       % - array of four parameters
 101       % TODO : add control for arrays of lines.
 102       var = varargin{1};
 103
 104       if size(var, 2)==4
 105           % 4 parameters of the line in a single array.
 106           line = var;
 107       elseif size(var, 2)==1
 108           % 1 parameter : angle of the line, going through origin.
 109           line = [zeros(size(var)) zeros(size(var)) cos(var) sin(var)];
 110       else
 111           error('wrong number of dimension for arg1 : can be 1 or 4');
 112       end
 113
 114   elseif length(varargin)==2
 115       % 2 input parameters. They can be :
 116       % - line angle and signed distance to origin.
 117       % - 2 points, then 2 arrays of 1*2 double.
 118       v1 = varargin{1};
 119       v2 = varargin{2};
 120       if size(v1, 2)==1
 121           % first param is angle of line, and second param is signed distance
 122           % to origin.
 123           line = [v1.*cos(v2) v1.*sin(v2) -sin(v2) cos(v2)];
 124       else
 125           % first input parameter is first point, and second input is the
 126           % second point.
 127           line = [v1(:,1), v1(:,2), v2(:,1)-v1(:,1), v2(:,2)-v1(:,2)];
 128       end
 129
 130   elseif length(varargin)==3
 131       % 3 input parameters :
 132       % first one is a point belonging to the line,
 133       % second and third ones are direction vector of the line (dx and dy).
 134       p = varargin{1};
 135       line = [p(:,1) p(:,2) varargin{2} varargin{3}];
 136
 137   elseif length(varargin)==4
 138       % 4 input parameters :
 139       % they are x0, y0 (point belongng to line) and dx, dy (direction vector
 140       % of the line).
 141       % All parameters should have the same size.
 142       line = [varargin{1} varargin{2} varargin{3} varargin{4}];
 143   else
 144       error('Wrong number of arguments in ''createLine'' ');
 145   end
 146
 147 endfunction
 148
 149 %!test
 150 %! p1 = [1 1];
 151 %! p2 = [2 3];
 152 %! lin = createLine(p1, p2);
 153 %! assert (p1, lin(1,1:2), 1e-6);
 154 %! assert (p2-p1, lin(1,3:4), 1e-6);
 155
 156 %!test
 157 %! p1 = [1 1;1 1];
 158 %! p2 = [2 3;2 4];
 159 %! lin = createLine(p1, p2);
 160 %! assert (2, size(lin, 1));
 161 %! assert (p1, lin(:,1:2), 1e-6);
 162 %! assert (p2-p1, lin(:,3:4), 1e-6);
 163