5.7. Kuvien yhdistäminen¶

Edellisen sivun piirtoprimitiivit maalaavat geometrisia merkintöjä kuvan päälle – viivan, suorakulmion, tekstinpätkän. Tämä kattaa useimmat merkinnät, jotka algoritmin on tehtävä näkyviksi, mutta ei kaikkia. Joskus merkintä on itse kuva: tallennettu vertailukehys näytettäväksi nykyisen rinnalla, aiemman tallennuksen pikkukuva esikatselun nurkassa, tai aiemmin tallennettu malli, joka visualisoidaan reaaliaikaisen kehyksen päälle kalibrointia varten. Mekanismi yhden kuvan piirtämiseksi toisen päälle on yksi ainoa metodi – draw_image() – jossa on tarpeeksi parametreja käsittelemään sijaintia, skaalausta, väripalettia ja läpinäkyvyyttä, joita todellinen yhdistäminen tarvitsee.

5.7.1. Peruskutsu¶

Yksinkertaisimmassa muodossaan draw_image ottaa vastaan toisen Image-olion ja sijainnin, johon se piirretään:

reference = image.Image("/sdcard/reference.bmp")
img.draw_image(reference, x=10, y=10)

Kohde on img; lähde on reference; lähteen vasen yläkulman pikseli osuu kohdan (10, 10) kohdalle kuvassa img, ja loput lähteen pikselit seuraavat siitä oikealle ja alaspäin. Kohteen pikselit, jotka lähde peittää, korvataan lähteen vastaavilla pikseleillä; lähteen jalanjäljen ulkopuoliset pikselit jätetään koskemattomiksi.

Jos lähde ulottuu kohteen reunan yli, sen ulkopuolelle jäävät osat leikataan hiljaisesti pois – sama armollinen käyttäytyminen, jota set_pixel osoittaa sallitun alueen ulkopuolisille sijainneille. Sovelluskoodin ei tarvitse rajata sijaintia kuvan mittoihin etukäteen; se voi välittää haluamansa sijainnin ja antaa metodin hoitaa leikkauksen.

5.7.2. Tiedoston lataaminen suoraan kutsussa¶

draw_image hyväksyy tiedostopolun Image-argumentin tilalle ja lataa tiedoston ennen sen yhdistämistä:

img.draw_image("/sdcard/reference.bmp", x=10, y=10)

Tämä näyttää käytännöllisyydeltä – yksi rivi kahden sijaan – ja sitä se onkin, mutta ero on enemmän kuin pelkkä syntaksi. Image-olion muodostaminen tiedostosta varaa puskurin dekoodattujen pikseleiden säilyttämiseen, ja tämä puskuri pysyy olemassa, kunnes roskienkeruu vapauttaa sen. Polun välittäminen suoraan metodille draw_image antaa moduulin dekoodata tiedoston väliaikaiseen puskuriin, yhdistää siitä ja vapauttaa puskurin, kun kutsu palaa, ilman että sovelluskoodin tarvitsee pitää viittausta erilliseen Image-olioon kehysten välissä.

5.7.3. Skaalaus¶

Kun lähde ja kohde ovat erikokoisia – matalan resoluution tallennus yhdistetään korkeamman resoluution kankaalle, tai pikkukuva, joka on mitoitettava tiettyyn osuuteen kehyksestä – kaksi skaalausparametria huolehtii lähteen koon muuttamisesta sitä piirrettäessä:

img.draw_image(reference, x=10, y=10, x_scale=2.0, y_scale=2.0)

x_scale ja y_scale ovat riippumattomia liukulukuja; molempien välittäminen samalla arvolla skaalaa tasaisesti, ja eri arvojen välittäminen venyttää tai kutistaa lähdettä yhdellä akselilla. Skaalaus tapahtuu piirtohetkellä; lähdettä reference ei muuteta.

Vihje-lippujen bittimaski päättää, kuinka skaalaus todellisuudessa interpoloi pikseleiden välillä. image.BILINEAR tuottaa tasaisempia tuloksia suuremman laskennan kustannuksella; image.BICUBIC tuottaa vielä tasaisempia tuloksia ja maksaa jälleen enemmän; oletus käyttää lähimmän naapurin menetelmää, joka on halvin ja oikea valinta, kun lähde on jo kohteen pikseliresoluutiossa. Kuvasuhteen käsittelyn liput – SCALE_ASPECT_KEEP, SCALE_ASPECT_EXPAND, SCALE_ASPECT_IGNORE – päättävät, mitä tehdä, kun lähteen kuvasuhde ei vastaa suorakulmiota, johon se piirretään.

5.7.4. Alfasekoitus¶

Oletuksena draw_image korvaa kohteen pikselit lähteen pikseleillä. Kun tavoitteena on läpikuultava päällys – jotta kohde näkyy lähteen läpi – alpha-parametri ohjaa, kuinka nämä kaksi sekoitetaan. alpha=0 näyttää vain kohteen (ei lähdettä); alpha=255 on oletus ja näyttää vain lähteen (täysi korvaus); väliarvot sekoittavat näitä kahta suhteellisesti:

img.draw_image(overlay, x=0, y=0, alpha=128)

Erillinen alpha_palette-argumentti on moduulin ainoa pikselikohtainen alfamekanismi. Se ottaa vastaan GRAYSCALE-kuvan, jonka arvoja käytetään alfana lähteen vastaavassa kohdassa – esimerkiksi lämpökartta, jonka alfa vaihtelee sen intensiteetin mukaan. Alfa on toimitettava tuona erillisenä harmaasävyargumenttina; lähdekuva, joka kantaa omaa alfakanavaansa (vaikkapa läpinäkyvyyden sisältävä PNG), ei tuo sitä mukanaan automaattisesti.

5.7.5. Lähteen ROI ja paletti¶

Kaksi muuta parametria täydentää yhdistämismekanismin:

roi=(x, y, w, h) rajoittaa lähteen sen omaan aliosuorakulmioon, jolloin vain tuo suorakulmio yhdistetään kohteeseen. Hyödyllinen rajaamiseen saman kutsun sisällä, ilman erillisen rajatun välivaiheen valmistelua.
color_palette korvaa kunkin lähdepikselin arvon hakutaulukon kautta ennen piirtämistä – sama mekanismi, jota metodit to_rainbow() ja to_ironbow() käyttävät, tarjottuna tässä, jotta päällys voidaan paletisoida matkalla kohteeseen ilman erillistä muunnosvaihetta.

Molemmat toimivat yhdessä kaiken muun kutsussa olevan kanssa: skaalauksen, alfan, kohdepuolen mask-argumentin ja kohdepuolen roi-parametrin kanssa, joka rajaa kirjoituksen kohteen suorakulmioon.