# VImage

Con esta clase podemos manejar imágenes independientes del hardware, permitiendo cargarlas y salvarlas en distintos formatos y de distintas fuentes. Dispone de funciones para modificar las imágenes como scaledToHeight que nos devuelve otra imagen a escala de la inicial y de la altura deseada. También dispone de funciones de modificación a nivel de pixel. También es usada como parámetro en funciones de otras clases como en [VRegister](vregister) ara indicar el icono de una pestaña.

Hay una serie de tipos de fichero soportados por defecto, pudiendo añadirse más mediante plugins. Los tipos de fichero soportados están en el enum de tipos de ficheros de esta clase.

Las funciones de manipulación de pixels dependen del formato de la imagen.

Si el formato es 32-bits a la función setPixel en el parámetro index\_or\_rgb le pasamos un valor 32-bits con el color rgb 0 rgba si maneja transparencias.

Si el formato es de 8-bits o monocromo el valor de index\_or\_rgb deberá ser el indice del color en la paleta de colores de la imagen.

## Funciones

**Constructor**

| Función             |
| ------------------- |
| [VImage](#vimage)() |

**Generales**

| Retorno | Función                                           |
| ------- | ------------------------------------------------- |
| Number  | [bitPlaneCount](#bitplanecount)()                 |
| Number  | [byteCount](#bytecount)()                         |
| Number  | [depth](#depth)()                                 |
| Numer   | [dotsPerMeterX](#dotspermeterx)()                 |
| Numer   | [dotsPerMeterY](#dotspermetery)()                 |
| Boolean | [hasAlphaChannel](#hasalphachannel)()             |
| Number  | [height](#height)()                               |
| Boolean | [isNull](#isnull)()                               |
| void    | [setDotsPerMeterX](#setdotspermeterx)( Number x ) |
| void    | [setDotsPerMeterY](#setdotspermetery)( Number y ) |
| Number  | [width](#width)()                                 |

**De Input/Output**

| Retorno                  | Función                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| Boolean                  | [load](#load)( String szPath )                                                                                                       |
| Boolean                  | [load](#boolean-load-string-szpath-string-szfiletype-)( String szPath, String szFileType )                                           |
| Boolean                  | [loadFromData](#loadfromdata)( VByteArray baBuffer, String szFileType )                                                              |
| Boolean                  | [loadResource](#loadresource)( String szIdRefDib )                                                                                   |
| Boolean                  | [save](#save)( String szPath )                                                                                                       |
| Boolean                  | [save](#boolean-save-string-szpath-string-szfiletype-number-ncalidad---1-)( String szPath, String szFileType, Number nCalidad = -1 ) |
| [VByteArray](vbytearray) | [saveToData](#savetodata)( String szFileType, Number nCalidad = -1 )                                                                 |

**De operaciones**

| Retorno | Función                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------- |
| VImage  | [copy](#copy)( Number x, Number y, Number width, Number height )                                           |
| VImage  | [copy](#vimage-copy)()                                                                                     |
| VImage  | [mirrored](#mirrored)( Boolean bHorizontal = false, Boolean bVertical = true )                             |
| VImage  | [scaled](#scaled)( Number width, Number height, Number aspectRatio = arIgnore, Number transform = tmFast ) |
| VImage  | [scaledToHeight](#scaledtoheight)( Number height, Number transform = tmFast )                              |
| VImage  | [scaledToWidth](#scaledtowidth)( Number width, Number transform = tmFast )                                 |

**De edición**

| Retorno | Función                                                            |
| ------- | ------------------------------------------------------------------ |
| void    | [fill](#fill)( Number pixelValue )                                 |
| void    | [invertPixels](#invertpixels)( Number inverMode )                  |
| Number  | [pixel](#pixel)( Number x, Numer y )                               |
| Number  | [pixelIndex](#pixelindex)( Number x, Numer y )                     |
| void    | [setPixel](#setpixel)( Number x, Number y, Number index\_or\_rgb ) |

**De textos (no soportado en todos los formatos)**

| Retorno | Función                                            |
| ------- | -------------------------------------------------- |
| void    | [setText](#settext)( String szKey, String szText ) |
| String  | [text](#text)( String szKey )                      |

## Enumeraciones

**Modo de transformación**

* 0 = Transformación rápida: al escalar la imagen la transformación se realiza rápidamente, sin ningún tipo de suavizado.
* 1 = Transformación suave: la imagen resultante se transforma utilizando el filtrado bilineal (Su función es aplicar las texturas, para cada uno de los puntos de una imagen en concordancia con los que le rodean, para de este modo lograr una mayor suavidad de las figuras).

**Tipos de ficheros**

* BMP = Windows Bitmap (Read/Write)
* GIF = Graphic Interchange Format (opcional) (Read)
* JPG = Joint Photographic Experts Group (Read/Write)
* JPEG = Joint Photographic Experts Group (Read/Write)
* PNG = Portable Network Graphics (Read/Write)
* PBM = Portable Bitmap (Read)
* PGM = Portable Graymap (Read)
* PPM = Portable Pixmap (Read/Write)
* TIFF = Tagged Image File Format (Read/Write)
* XBM = X11 Bitmap (Read/Write)
* XPM = X11 Pixmap (Read/Write)

## Documentación de funciones

### Constructor

#### VImage() <a href="#vimage" id="vimage"></a>

Constructor de la clase.

Con esta clase podemos manejar imágenes independientes del hardware, permitiendo cargarlas y salvarlas en distintos formatos y de distintas fuentes. Dispone de funciones para modificar las imágenes como scaledToHeight que nos devuelve otra imagen a escala de la inicial y de la altura deseada. También dispone de funciones de modificación a nivel de pixel. También es usada como parámetro en funciones de otras clases en [VRegister](vregister) para indicar el icono de una pestaña, etc.

### Funciones generales

#### Number bitPlaneCount() <a href="#bitplanecount" id="bitplanecount"></a>

Retorna el número de planos de bits de la imagen. El número de planos de bits de la imagen es el número de bits de información de color y transparencia para cada píxel. Este número es diferente de la profundidad de bits cuando el formato de imagen contiene bits que no se usan.

#### Number byteCount() <a href="#bytecount" id="bytecount"></a>

Retorna el número de bytes ocupado por los datos que componen la imagen.

#### Number depth() <a href="#depth" id="depth"></a>

Devuelve la profundidad de la imagen. la profundidad de la imagen es el número de bits usados para guardar información de un píxel, también denominado bits por píxel (bpp). Las profundidades soportadas son: 1, 8, 16, 24 y 32.

#### Numer dotsPerMeterX() <a href="#dotspermeterx" id="dotspermeterx"></a>

Devuelve el número de píxeles horizontales por metro (físico). Junto con dotsPerMeterY() este número define la escala y el aspecto de imagen pretendidos.

#### Numer dotsPerMeterY() <a href="#dotspermetery" id="dotspermetery"></a>

Devuelve el número de píxeles verticales por metro (físico). Junto con dotsPerMeterX() este número define la escala y el aspecto de imagen pretendidos.

#### Boolean hasAlphaChannel() <a href="#hasalphachannel" id="hasalphachannel"></a>

Devuelve true si la imagen tiene un formato que respeta el canal alfa, en caso contrario devuelve false.

#### Number height() <a href="#height" id="height"></a>

Devuelve la altura de la imagen en píxeles.

#### Boolean isNull() <a href="#isnull" id="isnull"></a>

Devuelve true si la imagen es nula. En caso contrario devuelve false. Una imagen nula tiene todos los parámetros a 0 y no tiene datos alojados.

#### void setDotsPerMeterX( Number x ) <a href="#setdotspermeterx" id="setdotspermeterx"></a>

Establece el número de píxeles que ocupan horizontalmente un metro (físico).

#### void setDotsPerMeterY( Number y ) <a href="#setdotspermetery" id="setdotspermetery"></a>

Establece el número de píxeles que ocupan verticalmente un metro (físico).

#### Number width() <a href="#width" id="width"></a>

Devuelve el ancho de la imagen en píxeles.

### Funciones de Input/Output

#### Boolean load( String szPath ) <a href="#load" id="load"></a>

Carga una imagen de disco correspondiente a la senda especificada. Deduce el formato tratando de leer la cabecera.

Parámetros:

* szPath: cadena que contiene la senda de la imagen.

#### Boolean load( String szPath, String szFileType )

Carga una imagen de disco correspondiente a la senda especificada. Devuelve true si la imagen pudo ser cargada, en caso contrario devuelve false. En la carga trata de leer la imagen usando el formato especificado (PNG, JPG, etc.). Si no especificamos formato trata de leer la cabecera para deducir el formato.

Parámetros:

* szPath: cadena que contiene la senda de la imagen.
* szFileType: cadena que indica el formato de la imagen.

#### Boolean loadFromData( VByteArray baBuffer, String szFileType ) <a href="#loadfromdata" id="loadfromdata"></a>

Carga una imagen de un objeto de la clase [VByteArray](vbytearray). Si no especificamos formato trata de leer la cabecera para deducir el formato.

Parámetros:

* baBuffer: buffer, objeto de la clase [VByteArray](vbytearray) que contiene la imagen.
* szFileType: cadena que indica el formato de la imagen.

Esta función ha sido incluida en la versión 7.15 del API.

#### Boolean loadResource( String szIdRefDib ) <a href="#loadresource" id="loadresource"></a>

Carga una imagen del proyecto.

Parámetros:

* szIdRefDib: cadena que contiene el identificador referencia de la imagen en el proyecto (ALIAS/ID).

#### Boolean save( String szPath ) <a href="#save" id="save"></a>

Guarda la imagen a un fichero. Se guardará en el formato que se corresponda con la extensión que definimos para el nombre del fichero.

Parámetros:

* szPath: cadena que indica la senda del fichero para guardar la imagen.

#### Boolean save( String szPath, String szFileType, Number nCalidad = -1 )

Guarda la imagen a un fichero, usando el formato y la calidad que pasamos como parámetros. Si el formato es 0, se guardará en el formato que se corresponda con la extensión que definimos para el nombre del fichero. Devuelve true si la imagen ha sido guardada, en caso contrario devuelve false.

Parámetros:

* szPath: cadena que indica la senda del fichero para guardar la imagen.
* szFileType: formato de la imagen.
* nCalidad: número que indica la calidad de la imagen. El factor de calidad debe estar entre 0 y 100, o -1. Especifica 0 para realizar la menor compresión, 100 para ficheros grandes sin comprimir y -1 (por defecto) para usar los valores por defecto.

#### VByteArray saveToData( String szFileType, Number nCalidad = -1 ) <a href="#savetodata" id="savetodata"></a>

Devuelve un objeto de la clase [VByteArray](vbytearray) de retorno devolverá true.

Parámetros:

* szFileType: formato de la imagen.
* nCalidad: número que indica la calidad de la imagen. El factor de calidad debe estar entre 0 y 100, o -1. Especifica 0 para realizar la menor compresión, 100 para ficheros grandes sin comprimir y -1 (por defecto) para usar los valores por defecto.

Esta función ha sido incluida en la versión 7.15 del API.

### Funciones de operaciones

#### VImage copy( Number x, Number y, Number width, Number height ) <a href="#copy" id="copy"></a>

Devuelve una imagen que es una subárea de la imagen original.

Parámetros:

* x: número que indica la coordenada x dentro de la imagen.
* y: número que indica la coordenada y dentro de la imagen.
* width: número que indica el ancho del subárea.
* height: número que indica el alto del subárea.

#### VImage copy()

Devuelve una copia de la imagen.

#### VImage mirrored( Boolean bHorizontal = false, Boolean bVertical = true ) <a href="#mirrored" id="mirrored"></a>

Devuelve una imagen especular, bien en dirección horizontal o en vertical, dependiendo de los parámetros. La imagen se puede obtener transformada en ambas direcciones. La imagen original no se cambia.

Parámetros:

* bHorizontal: booleano que indica la dirección horizontal para la imagen especular.
* bVertical: booleano que indica la dirección vertical para la imagen especular.

#### VImage scaled( Number width, Number height, Number aspectRatio = arIgnore, Number transform = tmFast ) <a href="#scaled" id="scaled"></a>

Devuelve una copia de la imagen escalada al rectángulo definido, el ratio de aspecto y el modo de transformación definidos como parámetro.

Parámetros:

* width: número que indica el ancho del rectángulo.
* height: número que indica el alto del rectángulo.
* aspectRatio: número que indica la relación del alto y ancho final con respecto al original. Ver enum de Qt::AspectRatioMode
* transform: número que indica el modo de transformación. Ver enum de modo de transformación.

#### VImage scaledToHeight( Number height, Number transform = tmFast ) <a href="#scaledtoheight" id="scaledtoheight"></a>

Devuelve una copia de la imagen escalada. La imagen devuelta sera escalada a la altura definida como parámetro y de acuerdo al modo de transformación. La función calcula automáticamente el ancho de la imagen para que el ratio de aspecto de la imagen se mantenga.

Parámetros:

* height: número que indica el alto del rectángulo.
* transform: número que indica el modo de transformación. Ver enum de modo de transformación.

#### VImage scaledToWidth( Number width, Number transform = tmFast ) <a href="#scaledtowidth" id="scaledtowidth"></a>

Devuelve una copia de la imagen escalada. La imagen devuelta será escalada al ancho definida como parámetro y de acuerdo al modo de transformación. La función calcula automáticamente el ancho de la imagen para que el ratio de aspecto de la imagen se mantenga.

Parámetros:

* width: número que indica el ancho del rectángulo.
* transform: número que indica el modo de transformación. Ver enum de de modo de transformación.

### Funciones de edición

#### void fill( Number pixelValue ) <a href="#fill" id="fill"></a>

Rellena la imagen entera con el valor dado. Si la profundidad de imagen es 1, únicamente el bit bajo es usado. Es decir, fill(0), fill(2), etc., rellenan la imagen con 0, fill(1), fill(3), rellenan la imagen con 1. De igual forma, si la profundidad de la imagen es 8, se usan los 8 bits bajos, al igual que en el caso de 16 bits.

#### void invertPixels( Number inverMode ) <a href="#invertpixels" id="invertpixels"></a>

Invierte todos los valores correspondientes al pixel en la imagen.

Parámetros:

* inverMode: número que indica el modo de inversión, válido únicamente para imágenes de profundidad 32 bits. El modo por defecto es InvertRgb, que no modifica el canal alfa. Si el modo es InvertRgba, los bits correspondientes al canal alfa también son invertidos.

Invertir una imagen de 8 bits significa reemplazar todos los píxeles con índice de color i con un píxel por el índice de color -i. Lo mismo sucede en el caso de las imágenes de 1 bit. La tabla de colores no se cambia.

#### Number pixel( Number x, Numer y ) <a href="#pixel" id="pixel"></a>

Devuelve el color del píxel en la posición que pasamos como parámetro. Si la posición no es válida, el resultado es indefinido.

Advertencia: esta función consume muchos recursos si la usamos para manipulaciones masivas de píxeles.

#### Number pixelIndex( Number x, Numer y ) <a href="#pixelindex" id="pixelindex"></a>

Devuelve el index del píxel en la posición que pasamos como parámetro. Si la posición no es válida, o la imagen no tiene paleta ( depth()

\>

8\), los resultados son indefinidos.

#### void setPixel( Number x, Number y, Number index\_or\_rgb ) <a href="#setpixel" id="setpixel"></a>

Establece el valor del index del píxel o el color en la posición indicada como parámetro.

Parámetros:

* x: número que indica la coordenada x del píxel en la imagen.
* y: número que indica la coordenada y del píxel en la imagen.
* index\_or\_rgb: número que indica el index (posición del color en la tabla o paleta de colores de la imagen) o color en formato rgb (Ver QRgb).

Si el formato de la imagen es monocromo o 8 bits, el index indicado debe tener un valor de los que contiene la tabla de colores de la imagen. En el resto de los casos el parámetro ha de ser el valor RGB. Si la posición no es válida o nos salimos de la paleta de colores de la imagen, el resultado es indefinido.

Advertencia: esta función consume muchos recursos si la usamos para manipulaciones masivas de píxeles.

### Funciones de textos (no soportado en todos los formatos)

#### void setText( String szKey, String szText ) <a href="#settext" id="settext"></a>

Establece el texto de la imagen y asocia éste con la clave que pasamos como parámetro. Si únicamente queremos guardar un bloque de texto (es decir, un comentario o una descripción corta), podemos dejar vacía la clave o usar una genérica como "Description". El texto de la imagen es embebido dentro los datos de la imagen cuando usamos la función save(). No todos los formatos de imagen soportan textos embebidos.

Parámetros:

* szKey: cadena que indica la clave en la que se incluirá el texto.
* szText: texto que se incluirá en la imagen.

#### String text( String szKey ) <a href="#text" id="text"></a>

Devuelve el texto de la imagen asociado con la clave que pasamos como parámetro.

Parámetros:

* szKey: cadena que indica la clave cuyo texto queremos recuperar. Si no especificamos clave, devuelve todo el texto que contenga la imagen, con cada pareja de clave y texto separados por un cambio de línea.

## Ejemplos

### 1. Importar una imagen de disco

```javascript
importClass( "VImage" );

// Lanzamos el cuadro de dialogo "Abrir fichero"
var path = theMainWindow.fileDialogGetOpenFileName( "Abrir imagen", "", "*.jpg;*.bmp;*.png");

if ( path.length > 0 )
{
    // Creamos una imagen y cargamos el fichero
    var img = new VImage();

    if ( img.load(path) )
    {
        // Cogemos el control FOTO y le pasamos la imagen
        var edFoto = theRoot.dataView().control( "ED_FOTO" );

        edFoto.setImage( img );
    }
    else
        alert("No se ha podido cargar la imagen: " + path);
}
```
