mlib_ImageGridWarp(3mlib)

1mlib_ImageGridWarp(3MLIB) mediaLib Library Functions mlib_ImageGridWarp(3MLIB)
2
3
4

NAME

6       mlib_ImageGridWarp - grid-based image warp
7

SYNOPSIS

9       cc [ flag... ] file... -lmlib [ library... ]
10       #include <mlib.h>
11
12       mlib_status mlib_ImageGridWarp(mlib_image *dst, const mlib_image *src,
13            const mlib_f32 *xWarpPos, const mlib_f32 *yWarpPos,
14            mlib_d64 postShiftX, mlib_d64 postShiftY,
15            mlib_s32 xStart, mlib_s32 xStep, mlib_s32 xNumCells,
16            mlib_s32 yStart, mlib_s32 yStep, mlib_s32 yNumCells,
17            mlib_filter filter, mlib_edge edge);
18
19

DESCRIPTION

21       The  mlib_ImageGridWarp()  function performs a regular grid-based image
22       warp. The images must have the same type, and the same number of  chan‐
23       nels.  The images can have 1, 2, 3, or 4 channels. The data type of the
24       images can be MLIB_BYTE, MLIB_SHORT, MLIB_USHORT, or MLIB_INT. The  two
25       images may have different sizes.
26
27
28       The  image  pixels  are assumed to be centered at .5 coordinate points.
29       For example, the upper-left corner pixel of  an  image  is  located  at
30       (0.5, 0.5).
31
32
33       For  each pixel in the destination image, its center point D is, first,
34       backward mapped to a point S in the source image; then the source  pix‐
35       els  with  their  centers surrounding point S are selected to do one of
36       the interpolations specified by the filter parameter  to  generate  the
37       pixel value for point D.
38
39
40       The mapping from destination pixels to source positions is described by
41       bilinear interpolation between a rectilinear grid of points with  known
42       mappings.
43
44
45       Given  a  destination  pixel  coordinate (x, y) that lies within a cell
46       having corners at (x0, y0), (x1, y0),  (x0,  y1)  and  (x1,  y1),  with
47       source  coordinates  defined  at  each respective corner equal to (sx0,
48       sy0), (sx1, sy1), (sx2, sy2) and (sx3, sy3), the source  position  (sx,
49       sy) that maps onto (x, y) is given by the formulas:
50
51           xfrac = (x - x0)/(x1 - x0)
52           yfrac = (y - y0)/(y1 - y0)
53
54           s = sx0 + (sx1 - sx0)*xfrac
55           t = sy0 + (sy1 - sy0)*xfrac
56
57           u = sx2 + (sx3 - sx2)*xfrac
58           v = sy2 + (sy3 - sy2)*xfrac
59
60           sx = s + (u - s)*yfrac - postShiftX
61           sy = t + (v - t)*yfrac - postShiftY
62
63
64
65       In other words, the source x and y values are interpolated horizontally
66       along the top and bottom edges of the grid cell, and  the  results  are
67       interpolated vertically:
68
69                  (x0, y0) ->            (x1, y0) ->
70                    (sx0, sy0)             (sx1, sy1)
71                     +------------+---------+
72                     |           /|         |
73                     |     (s, t) |         |
74                     |            |         |
75                     |            |         |
76                     |            |         |
77                     |            |         |
78                     | (x, y) ->  |         |
79                     |  (sx, sy)--+         |
80                     |            |         |
81                     |            |         |
82                     |            | (u, v)  |
83                     |            |/        |
84                     +------------+---------+
85                  (x0, y1) ->          (x1, y1) ->
86                    (sx2, sy2)           (sx3, sy3)
87
88
89
90       The  results of above interpolation are shifted by (-postShiftX, -post‐
91       ShiftY) to produce the source pixel coordinates.
92
93
94       The destination pixels that lie outside of  any  grid  cells  are  kept
95       intact.  The  grid  is  defined by a set of equal-sized cells. The grid
96       starts at (xStart, yStart). Each cell has  width  equal  to  xStep  and
97       height  equal  to yStep, and there are xNumCells cells horizontally and
98       yNumCells cells vertically.
99
100
101       The degree of warping within each cell is  defined  by  the  values  in
102       xWarpPos and yWarpPos parameters. Each of these parameters must contain
103       (xNumCells + 1)*(yNumCells + 1) values,  which,  respectively,  contain
104       the source X and source Y coordinates that map to the upper-left corner
105       of each cell in the destination image. The cells are enumerated in row-
106       major  order.  That  is, all the grid points along a row are enumerated
107       first, then the grid points for the next row are enumerated, and so on.
108
109
110       For example, suppose xNumCells is equal to 2 and yNumCells is equal  to
111       1. Then the order of the data in the xWarpPos would be:
112
113           x00, x10, x20, x01, x11, x21
114
115
116
117       and in the yWarpPos:
118
119           y00, y10, y20, y01, y11, y21
120
121
122
123       for a total of (2 + 1)*(1 + 1) = 6 elements in each table.
124

PARAMETERS

126       The function takes the following arguments:
127
128       dst           Pointer to destination image.
129
130
131       src           Pointer to source image.
132
133
134       xWarpPos      A  float  array of length (xNumCells + 1)*(yNumCells + 1)
135                     containing horizontal warp positions at the grid  points,
136                     in row-major order.
137
138
139       yWarpPos      A  float  array of length (xNumCells + 1)*(yNumCells + 1)
140                     containing vertical warp positions at the grid points, in
141                     row-major order.
142
143
144       postShiftX    The displacement to apply to source X positions.
145
146
147       postShiftY    The displacement to apply to source Y positions.
148
149
150       xStart        The minimum X coordinate of the grid.
151
152
153       xStep         The horizontal spacing between grid cells.
154
155
156       xNumCells     The number of grid cell columns.
157
158
159       yStart        The minimum Y coordinate of the grid.
160
161
162       yStep         The vertical spacing between grid cells.
163
164
165       yNumCells     The number of grid cell rows.
166
167
168       filter        Type  of  resampling filter. It can be one of the follow‐
169                     ing:
170
171                       MLIB_NEAREST
172                       MLIB_BILINEAR
173                       MLIB_BICUBIC
174                       MLIB_BICUBIC2
175
176
177
178       edge          Type of edge condition. It can be one of the following:
179
180                       MLIB_EDGE_DST_NO_WRITE
181                       MLIB_EDGE_SRC_PADDED
182
183
184

RETURN VALUES

186       The function returns MLIB_SUCCESS if successful. Otherwise  it  returns
187       MLIB_FAILURE.
188

ATTRIBUTES

190       See attributes(5) for descriptions of the following attributes:
191
192
193
194
195       ┌─────────────────────────────┬─────────────────────────────┐
196       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
197       ├─────────────────────────────┼─────────────────────────────┤
198       │Interface Stability          │Committed                    │
199       ├─────────────────────────────┼─────────────────────────────┤
200       │MT-Level                     │MT-Safe                      │
201       └─────────────────────────────┴─────────────────────────────┘
202

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

ATTRIBUTES

SEE ALSO