mlib_ImageGridWarpTable_Fp(3mlib)

1mlib_ImageGridWarpTable_Fp(m3eMdLiIaBL)ib Library Funmcltiibo_nIsmageGridWarpTable_Fp(3MLIB)
2
3
4

NAME

6       mlib_ImageGridWarpTable_Fp  -  grid-based  image warp with table-driven
7       interpolation
8

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS

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

RETURN VALUES

182       The function returns MLIB_SUCCESS if successful. Otherwise  it  returns
183       MLIB_FAILURE.
184

ATTRIBUTES

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

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

ATTRIBUTES

SEE ALSO