HaloStack

Panu Lahtinen (pnuu a iki fi)

Same in English in here.

Sisältö:

HaloStack on yksinkertainen, käyttöjärjestelmäriippumaton Python-ohjelma kuvien pinoamista varten. Ohjelma on suunnattu lähinnä halokuvien pinoamiseen, ja se on toistaiseksi vain komentoriviohjelma. Graafinen käyttöliittymä on tulossa, joskus. Ohjelmaan on toteutettu yksinkertainen kohdistusmenetelmä, joka toimii parhaiten jos halokuvat on otettu käyttäen tummaa peittäjää, jonka läpi Aurinko vielä kuitenkin näkyy. Pinoaminen toimii myös muiden jalustalta otettujen kanssa suhteellisen hyvin, mutta laskenta hidastuu kohdistuspisteen suuremman koon takia.

Ohjelma tallentaa kuvat PNG-muodossa. Keskiarvopinot tallennetaan 16-bittiä/kanava sisältävinä riippumatta siitä ovatko lähtökuvat olleet 8-bittisiä (kuten JPG), tai suuremman bittisyvyyden omaavia (kameroiden raakaformaatin kuvat tai 16-bittiset TIFF-kuvat). Muut pinot tallennetaan samalla bittisyvyydellä kuin alkuperäiset kuvat.

Perusominaisuuksien käyttämiseksi tarvitaan Python-ohjelmointikielen tulkki, johon on asennettu Numpy- ja PythonMagick-kirjastot.

Tiettyjen lisäominaisuuksien käyttämiseksi tarvitaan lisäksi:

  • UFRaw - kameroiden raakakuvaformaattien lukemiseksi PythonMagick:n kautta. Tämä toimii luultavasti vain Linuxissa
  • h5py - HDF5-kirjasto Pythonille mediaanipinoamista varten
  • SciPy-kirjasto Pythonille kuvien kiertämistä varten

Asennus

Ubuntu

Asennus tapahtuu purkamalla skriptit alla olevasta paketista sopivaan hakemistoon. Skriptin voi ajaa suoraan ilman python -komentoa skriptin edessä, kunhan tiedosto löytyy ohjelmapolusta (esim. kotihakemostossa oleva bin-hakemisto). Katso käyttöesimerkkejä alempaa.

Lataa HaloStack v0.1.2 Python-skriptit tästä .tar.gz tai .zip.

Avaa terminaali, ja kopioi alla oleva komento asentaaksesi tarvittavat paketit:
sudo apt-get install python python-numpy python-pythonmagick ufraw python-h5py python-scipy

Windows

Windows-käyttäjille on kaksi vaihtoehtoa. Joko käyttää yhteen pakettiin kasattua settiä, tai lataa alla olevat riippuvuudet. Suosittelen ensimmäistä vaihtoehtoa, jos et itse ole tekemässä muutoksia koodiin.

Lataa HaloStack 0.1.2 Windowsille: 32-bit, 64-bit

Vaihtoehtoiseen Windows-asennukseen tarvittavat paketit (näitä ei tarvita yo. version kanssa!):
  • HaloStack-skriptit, ks. kohta "Asennus Ubuntuun"
  • Python (versio 2.x)
  • Numpy
  • PythonMagick (sama versio kuin Python-asennuksesi)
  • h5py (valinnainen, tarvitaan mediaanipinojen tekemiseen)
  • SciPy (valinnainen, tarvitaan kuvien kiertämiseen)
  • UFRaw (valinnainen, tarvitaan raakakuvien lukemiseen, ei testattu Windowsissa)

TODO-lista

Alla listatut ominaisuudet ovat suunnitelmissa, mutta ne eivät ole vielä valmiita.

  • Graafinen käyttöliittymä
  • logitiedoston kirjoittaminen

Komentoriviparametrit

-a FILE, --average-stack FILE
    Laskee keskiarvopinonen ja tallentaa tuloskuvan 16-bit/kanava
    PNG-kuvana tiedostoon FILE (esim. keskiarvo.png).
-m FILE, --max-intensity-stack FILE
    Jokaiseen pikseliin valitaan pinosta ko. kohdassa oleva pikseli,
    jossa värikanavien yhteiskirkkaus on suurin (R+G+B saa suurimman
    arvon). Kuva tallennetaan tiedostonimellä FILE (esim. maksimi.png)
    samalla värisyvyydellä (8- tai 16-bit/kanava) kuin lähtökuvat.
-M FILE, --max-deviation-stack FILE
    Jokaiseen pikseliin valitaan pinosta ko. kohdassa oleva pikseli,
    jossa värikanavien keskihajonta on suurin. Kuva tallennetaan
    tiedostonimellä FILE (esim. suurin_varihajonta.png) samalla
    värisyvyydellä (8- tai 16-bit/kanava) kuin lähtökuvat.
-c FILE, --max-color-diff FILE
    Jokaiseen pikseliin valitaan ko. kohdassa oleva pikseli, jossa
    kirkkaimman ja himmeimmän värikanavan erotus on mahdollisimman
    suuri, eli max(R,G,B) - min(R,G,B) saa suurimman arvon. Kuva
    tallennetaan tiedostonimellä FILE (esim. suurin_variero.png)
    samalla värisyvyydellä (8- tai 16-bit/kanava) kuin lähtökuvat.
-e FILE, --median FILE
    Jokaiseen pikseliin lasketaan ko. kohdassa olevien pikselien
    mediaani. Suurella kuvamäärällä tämä operaatio on hyvin hidas, ja
    vaatii todella paljon kiintolevyn käyttöä. Kuva tallennetaan
    tiedostonimellä FILE (esim. mediaani.png) samalla värisyvyydellä
    (8- tai 16-bit/kanava) kuin lähtökuvat.
-u R,A[,S[,T]], --pre-usm R,A[,S[,T]]
    Ennen pinoamista kuvia terävöitetään epäterävällä maskilla (USM,
    Unsharp Mask).
    R - maskin säde pikseleinä, esim. 40
    A - terävöityksen määrä, esim. 2.5 (Photoshopissa 250 %)
    S - sigma, maskin säteen suuntainen painotuskerroin, esim. 20.
        Valinnainen. Jos arvoa ei anneta, käytetään arvoa R/2.
    T - kynnysarvo, Vain pikselit joiden kirkkaus on suurempi kuin annettu 
        luku huomioidaan terävöityksessä. Valinnainen.
-U R,A[,S[,T]], --post-usm R,A[,S[,T]]
    Ennen tallennusta valmiit pinot terävöitetään epäterävällä
    maskilla (USM, Unsharp Mask). Katso parametrien määrittelyt yltä.
-b FILE, --base-image FILE
    Kuvaa FILE käytetään pinon vertailukohtana kohdistettaessa ja
    kuvienvälisen kirkkauden yhtenäistämisessä. Jos tiedostoa ei
    anneta, kuvasarjan ensimmäinen kuva toimii vertailukohtana.
-r x,y,s, --align-reference x,y,s
    Kohdista kuvat etsimällä jokaisesta kuvasta annettua
    vertailukohtaa parhaiten vastaava piste. Vertailualue määritellään
    antamalla paikan keskipiste (x,y) sekä alueen määrittävän neliön
    sivu, jonka sivunpituus on annetusta luvusta laskettuna
    2s+1. Pikselikoordinaattien nollakohta (0,0) on kuvan vasemmassa
    ylänurkassa. Vertailudatana käytetään (ilman lisämäärittelyjä)
    kuvasarjan ensimmäisestä kuvasta ko. alueelta saatuja pikseleitä.
    Paras sovitus määritetään etsimällä pienin arvo pikselien
    erotuksen neliölle. Vertailukuvan voi määrittää vapaasti -b
    -valinnalla.
-s x1,y1,x2,y2, --align-search-area x1,y1,x2,y2
    Kuvien kohdistamista voi nopeuttaa määrittelemällä alueen, jolla
    kohdistuspiste sijaitsee kaikissa kuvissa. Alueen määrittämiseksi
    syötetään alueen vasen ylänurkka (x1,y1) sekä oikea alanurkka
    (x2,y2). Pikselikoordinaattien nollakohta (0,0) on kuvan
    vasemmassa ylänurkassa.
-n NUM, --normalize NUM
    Yhtenäistetään kuvien keskinäinen kirkkaus ennen pinoamista. Luku
    NUM määrittää tason johon kuvien keskimääräinen kirkkaus
    säädetään. Jos NUM on nolla, käytetään ensimmäisen kuvan (tai -b
    -valinnalla osoitetun kuvan) keskimääräistä kirkkautta
    vertailukohtana.
-N x1,y1,x2,y2, --normalize-area x1,y1,x2,y2
    Määritä kuvien välisen normalisaation laskemiseen käytettävä
    alue. Alue rajataan antamalla alueen vasemman ylänurkan (x1,y1) ja
    oikean alanurkan (x2,y2) pikselikoordinaatit. Koordinaattien
    nollakohta (0,0) on kuvan vasemmassa ylänurkassa.
-t NUM, --correlation-threshold NUM
    Tällä vivulla voit määrittää pienimmän korrelaatiokertoimen (R^2),
    jolla kohdistetut kuvat vielä hyväksytään mukaan
    pinottaviksi. Korrelaatiokertoimen arvo on välillä 0.0 - 1.0,
    jossa 1.0 on täydellinen yhteneväisyys. Oletuksena kaikki kuvat
    hyväksytään mukaan pinottavaksi (eli -t 0.0).
-R X1,Y2,X2,Y2,S, --rotate-points=X1,Y2,X2,Y2,S
    Määrittämällä kaksi kohdistuspistettä, (X1,Y1) ja (X2,Y2),
    horisontista sekä näissä kohdissa olevien neliöiden (joiden koot
    ovat 2*S+1 x 2*S+1 pikseliä) kuvien kiertymä voidaan korjata.
    Pikselikoordinaattien nollakohta on kuvan vasemmassa ylänurkassa.
-O STR, --output-images STR
    Tallenna yksittäiset kuvasarjan kuvat PNG-kuvina. Kuvien nimien
    loppuun lisätään STR (esim. -O kohdistettu ->
    IMG_1234_kohdistettu.png). Näiden kuvien avulla
    uudelleenpinoaminen on paljon nopeampaa kuin raakakuvista pinojen
    laskeminen. Koska kuvat tallennetaan kohdistamisen jälkeen, näistä
    kuvista voi tarkistaa kohdistuksen onnistuminen, ja tarvittaessa
    hienosäätää erillisellä kuvankäsittelyohjelmalla.

Käyttöesimerkkejä

Alla olevat esimerkkikomennot olettavat erillisen Python-tulkin käyttämistä. Jos käytössäsi on Windowsia varten tehty paketoitu versio, korvaa komennoissa "python halostack.py" pelkällä komennolla "halostack". Linuxissa voi käyttää myöskin pelkkää "halostack.py" komentoa ilman erillistä Python-tulkin kutsua.

  • Lasketaan keskiarvo kaikista nykyisessä hakemistossa olevista JPG-kuvista ja tallennetaan kuva keskiarvo.png -tiedostoon (16-bit/kanava).
        python halostack.py -a average.png *.JPG
    
  • Kerätään kuvaan pikselit, joissa on suurin kokonaiskirkkaus:
        python halostack.py -m maximum_intensity.png *.tiff
    
  • Kerätään kuvaan pikselit, joissa kirkkaimman ja himmeimmän värikanavan ero on mahdollisimman suuri, eli max(R,G,B) - min(R,G,B) saa suurimman arvon:
        python halostack.py -c maximum_color_difference.png *.Png
    
  • Kerätään kuvaan pikselit, joissa värikanavien välinen keskihajonta on suurin:
        python halostack.py -M maximum_color_deviation *.jpg
    
  • Lasketaan kuvaan jokaisen kohdakkain olevan pikselin mediaani. Tämä ominaisuus tarvitsee Pythonin h5py-kirjaston.
        python halostack.py -n median.png *.TIF
    
  • Kohdistetaan kuvat ja lasketaan niistä keskiarvo. Tässä kohdistuksessa käytettävään kuvasarjan ensimmäisessä kuvassa kohdalla (x=300, y=1203) olevaa (2s+1 = 2*14+1 =) 25 pikseliä sivultaan olevaa neliötä. Pikselikoordinaatit lasketaan alkaen kuvan vasemmasta ylänurkasta (0,0). Tämä esimerkki on hidas, sillä kohdistuspistettä etsitään jokaisen kuvan koko kuva-alalta.
        python halostack.py -a average.png -r 300,1203,12 *.jpg
    
  • Sama kuin edellinen esimerkki, mutta nyt etsintäalue on rajattu käsittämään alueen, jonka vasen ylänurkka on (x1=250, y1=1150) ja oikea alanurkka (x2=400, y2=1300). Etsintäalue tulee asettaa niin suureksi, että kohdistuspiste mahtuu sen sisään kaikissa kuvissa.
        python halostack.py -a average.png -r 300,1203,12 -s 250,1150,400,1300 *.tif
    
  • Kuten edellinen esimerkki, mutta kohdistusalue on määritetty kuvasta "image42.tif"
        python halostack.py -a average.png -r 300,1203,12 -s 250,1150,400,1300 -b image42.tif *.tif
    
  • Terävöitetään kuvia ennen pinoamista epäterävällä maskilla (USM, Unsharp Mask), jonka säde on 40 pikseliä ja terävöityksen määrä 2.5 (Photoshopissa 250 %). Huomaa, ettei; sigma- ja threshold-parametrejä ole annettu, joten käytetään oletusarvoja s=r/2 = 40/2 = 20 ja t=0.
        python halostack.py -a average.png -u 40,2.5 *.jpg
    
  • Terävöitetään valmiit pinot epäterävällä maskilla:
        python halostack.py -a average.png -U 25,2.5 *.jpg
    
  • Yhtenäistetään kuvien kirkkaus ensimmäistä kuvaa vastaavaksi. Normalisointi tehdään ennen kohdistamista ja pinoamista.
        python halostack.py -m maximum_intensity.png -n 0 *.tif
    
  • Yhtenäistetään kuvien kirkkaus kuvasta "image42.tif" saatuun arvoon. Normalisoinnit lasketaan alueelta, jonka vasen ylänurkka kohdistetuissa kuvissa on (x1=300, y1=300) ja oikea alanurkka (x2=400, y2=400). Normalisoinnissa ko. alueiden keskikirkkaudet (mediaani) säädetään samoiksi.
        python halostack.py -m max_int.png -b image42.tif -n 0 -N 300,300,400,400 *.tif
    

Testimateriaalia

Tässä tarjolla esimerkkikuvia, joilla pinoamista voi kokeilla.

  • Marko Riikosen 20.4.2012 kuvaama sarja pyramidihaloista Auringon ympärillä: linkki
    • Esimerkkikomento (Windows-paketin versio):
    • halostack -a keskiarvo.png -r 772,648,9 -s 750,620,795,670 DSC_*
  • Marko Riikosen 9.4.2012 kuvaama pintahalonäytelmä: linkki
    • Esimerkkikomento (Windows-paketin versio):
    • halostack -m maksimi.png -r 615,497,9 -s 590,470,640,515 U*jpg
  • Panu Lahtisen kuvasarja ilman peittäjää (huomaa suurempi kohdistusalueen arvo: 40 pikseliä suuntaansa Auringon keskipisteestä) 23.4.2012 olleesta kirkkaasta ylläsivuavanäytelmästä: linkki
    • Esimerkkikomento (Windows-paketin versio):
    • halostack -a keskiarvo.png -r 405,320,40 -s 370,290,440,350 *jpg