man/lqr_carver_bias_add_xy.3

   1 .\"     Title: \fBlqr_carver_bias_add\fR
   2 .\"    Author: Carlo Baldassi
   3 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   4 .\"      Date: 4 Maj 2009
   5 .\"    Manual: LqR library API reference
   6 .\"    Source: LqR library 0.4.0 API (3:0:3)
   7 .\"
   8 .TH "\FBLQR_CARVER_BIAS_ADD\FR" "3" "4 Maj 2009" "LqR library 0.4.0 API (3:0:3)" "LqR library API reference"
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 lqr_carver_bias_add_xy, lqr_carver_bias_add_area, lqr_carver_bias_add, lqr_carver_bias_add_rgb_area, lqr_carver_bias_add_rgb \- update an LqrCarver bias
  15 .SH "SYNOPSIS"
  16 .sp
  17 .ft B
  18 .nf
  19 #include <lqr\&.h>
  20 .fi
  21 .ft
  22 .HP 33
  23 .BI "LqrRetVal lqr_carver_bias_add_xy(LqrCarver*\ " "carver" ", gdouble\ " "bias" ", gint\ " "x" ", gint\ " "y" ");"
  24 .HP 35
  25 .BI "LqrRetVal lqr_carver_bias_add_area(LqrCarver*\ " "carver" ", gdouble*\ " "buffer" ", gint\ " "bias_factor" ", gint\ " "width" ", gint\ " "height" ", gint\ " "x_off" ", gint\ " "y_off" ");"
  26 .HP 30
  27 .BI "LqrRetVal lqr_carver_bias_add(LqrCarver*\ " "carver" ", gdouble*\ " "buffer" ", gint\ " "bias_factor" ");"
  28 .HP 39
  29 .BI "LqrRetVal lqr_carver_bias_add_rgb_area(LqrCarver*\ " "carver" ", gdouble*\ " "buffer" ", gint\ " "bias_factor" ", gint\ " "channels" ", gint\ " "width" ", gint\ " "height" ", gint\ " "x_off" ", gint\ " "y_off" ");"
  30 .HP 34
  31 .BI "LqrRetVal lqr_carver_bias_add_rgb(LqrCarver*\ " "carver" ", gdouble*\ " "buffer" ", gint\ " "bias_factor" ", gint\ " "channels" ");"
  32 .SH "FOREWORD"
  33 .PP
  34 All the functions described in this page are used to add a bias to
  35 LqrCarver
  36 objects\&. A positive biased pixel will be more likely to be avoided by seams, and thus be preserved during rescaling, while a negative bias has the opposite effect\&.
  37 .PP
  38 All of these functions must be called before
  39 \fBlqr_carver_resize\fR(3)\&. If called multiple times, the biases added at each call will sum up\&.
  40 .SH "ADDING A BIAS PIXEL BY PIXEL"
  41 .PP
  42 The function
  43 \fBlqr_carver_bias_add_xy\fR
  44 adds a bias to the
  45 \fIx\fR,
  46 \fIy\fR
  47 pixel of the image loaded into the
  48 LqrCarver
  49 object pointed to by
  50 \fIcarver\fR
  51 .PP
  52 A typical value for
  53 \fIbias_factor\fR
  54 would be
  55 1000
  56 (in absolute value)\&.
  57 .SH "ADDING A BIAS FROM A BUFFER"
  58 .PP
  59 The function
  60 \fBlqr_carver_bias_add_area\fR
  61 adds a bias to an area of the image loaded into the
  62 LqrCarver
  63 object pointed to by
  64 \fIcarver\fR\&.
  65 .PP
  66 The parameter
  67 \fIbuffer\fR
  68 must point to an array of
  69 \fBdoubles\fR
  70 of size
  71 \fIwidth\fR * \fIheight\fR, ordered first by rows, then by columns\&.
  72 .PP
  73 The offset of the area relative to the image can be specified through
  74 \fIx_off\fR
  75 and
  76 \fIy_off\fR\&. The bias area can exceed the boundary of the image, and the offsets can be negative\&.
  77 .PP
  78 The parameter
  79 \fIbias_factor\fR
  80 is an overall bias scale\&. A typical value when the buffer contents are of the order of
  81 1
  82 would be
  83 1000
  84 (in absolute value)\&.
  85 .PP
  86 The function
  87 \fBlqr_carver_bias_add\fR
  88 can be used when the area to add is of the same size of the image loaded in the
  89 LqrCarver
  90 object and the offsets are
  91 0\&.
  92 .SH "ADDING A BIAS FROM AN IMAGE"
  93 .PP
  94 The functions
  95 \fBlqr_carver_bias_add_rgb_area\fR
  96 and
  97 \fBlqr_carver_bias_add_rgb\fR
  98 are very similar to
  99 \fBlqr_carver_bias_add_area\fR
 100 and
 101 \fBlqr_carver_bias_add\fR, except that they use 8\-bit multi\-channel images as inputs\&.
 102 .PP
 103 The number of channels in the image is passed via the parameter
 104 \fIchannels\fR\&. The last channel is assumed to be the alpha (opacity) channel if
 105 \fIchannels\fR
 106 is equal to
 107 2
 108 or greater than
 109 3
 110 (if this is not the case, use the previous functions)\&.
 111 .PP
 112 The bias is computed from the average of the colour channels, multiplied by the value of the alpha channel if present\&. For example, in RGBA images a white, nontransparent pixel is equivalent to a value of
 113 1\&.0
 114 when using a buffer in
 115 \fBlqr_carver_bias_add_area\fR\&.
 116 .SH "RETURN VALUES"
 117 .PP
 118 The return values follow the Liquid Rescale library signalling system\&.
 119 .SH "SEE ALSO"
 120 .PP
 121
 122 \fBLqrRetVal\fR(3), \fBlqr_carver_init\fR(3), \fBlqr_carver_rigmask_add\fR(3)
 123 .SH "COPYRIGHT"
 124 Copyright \(co 2007-2009 Carlo Baldassi
 125 .br