CGG   JaGrLib:  KUCHAŘKA

Jazyk Java
JaGrLib v ULABu
Programátorské poklesky
Nefungují řádkové příkazy Java JDK
Jak si stáhnout aktuální verzi JaGrLib a Skel
Řádkové příkazy
Jak používat systém Ant
Jak pracovat v prostředí Eclipse
Jak pracovat v prostředí NetBeans
Jak přidat do JaGrLib zcela nový modul
Jak řešit zápočtovou úlohu
Jak zaregistrovat nebo přeregistrovat modul
Jak přidat nový parametr (Property)
Užitečné konstanty a funkce
Ladění, log-files
Jak vyrobit animaci
Podpora OpenGL
Scriptování v JaGrLib (anglicky)
"Ray-tracing" koncepce
"Radiosity" koncepce

Instruktážní videa:
Práce s řádkovou verzí SVN (10.2 MB)
Práce s TortoiseSVN (17.5 MB)
Práce s Eclipse 3.2 (starší a složitější verze) (49.8 MB)
Řešení zápočtové úlohy (59.1 MB)

Jazyk Java

JaGrLib potřebuje ke své práci jazyk Java verze alespoň 1.6 (J2SE version 6). Doporučuji původní JDK/JRE od firmy Sun, ale je pravděpodobné, že i jiné implementace budou bez velkých problémů fungovat. Je vyzkoušené, že JaGrLib je dobře přenositelné prostředí, minimálně mezi Windows a UNIX (Linux).

Verze 1.5 a nižší se nedají pro vývoj a spouštění JaGrLib použít!

Doporučené čtení:

Práce v UNIXovských laboratořích na MFF UK

Ukazuje se, že tam není všechno úplně jednoduché, proto zde shrnuji pár zásad:

JaGrLib potřebuje ke své práci jazyk Java

Nefungují řádkové příkazy Java JDK

Pravděpodobně je špatně nastaveno pár proměnných environmentu:

Někdy může být nekonzistentní hodnota klíčů v registrační databázi. Konkrétně se jedná o klíče:
HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\CurrentVersion
HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment\CurrentVersion
Obě hodnoty se mají rovnat aktuální (nejnovější) verzi nainstalovaných JDK a JRE. V našem případě "1.6".

Jak si stáhnout aktuální verzi JaGrLib a Skel

JaGrLib i Skel (GUI nadstavba) jsou součástí jediné SVN repository. Adresa (URL) repository je: svn://cgg.mff.cuni.cz/JaGrLib/trunk. Ke stažení je potřeba mít nainstalovaného SVN klienta - třeba řádkovou verzi nebo ve Windows populární TortoiseSVN.

Řádkovou verzí se aktuální JaGrLib stáhne pomocí: 

svn checkout svn://cgg.mff.cuni.cz/JaGrLib/trunk
Tím se vytvoří adresář trunk obsahující hlavní větev knihovny.
Pozdější update (aktualizace dat) ze serveru se provádí v příslušném adresáři příkazem: 
svn update

V TortoiseSVN stačí ukázat na adresář, kam se má "checkout" provést, a zvolit "SVN Checkout" z lokálního menu. V horní řádce vyplnit adresu "svn://cgg.mff.cuni.cz/JaGrLib/trunk", dole zadat podadresář, do kterého chceme knihovnu umístit..
Aktualizace dat se provádí příkazem "SVN Update" v příslušném adresáři.

Dvě krátká instruktážní videa: Práce s řádkovou verzí SVN (10.2 MB) a Práce s TortoiseSVN (17.5 MB).

Nyní lze použít i alternativní download knihovny: denně je aktualizován archiv JaGrLib.tgz.
Upozornění: 1. všechny textové soubory mají UNIXovské konce řádků, 2. archiv kopíruje vývoj SVN repository a bude se tedy měnit velmi často. Je třeba mít vždy aktuální verzi knihovny.

Řádkové příkazy

JaGrLib projekt lze překládat a spouštět jednoduchými řádkovými příkazy, k tomu není potřeba mít nainstalované žádné IDE prostředí (Eclipse, NetBeans) ani Ant. Pouze je nutné mít nainstalované JDK a JRE verze minimálně 1.6.

Řádkové příkazy:

compile.bat
překlad celé knihovny JaGrLib (bez ohledu na změněné soubory se překládá vždy kompletní knihovna - pro efektivnější vývoj doporučuji používat systém Ant)
run.bat [<main>] [<switches>] [<composition>] ...
spuštění některého z hlavních programů knihovny Skel:
<main> je nepovinná specifikace hlavní spouštěné třídy. Lze nechat prázdné "" pro spuštění Skelu (třída cz.cuni.jagrlib.Main) nebo lze zadat 00, 01, apod. pro spuštění jiných hlavních programů, např. cz.cuni.jagrlib.Main00
<switches> jsou nepovinné přepínače, např. "-d" pro zapnutí ladícího režimu (fungují výpisy LogFile.debug())
<composition> - kvůli rychlému spouštění lze přímo zadat sestavu, např. "data/sFractal.xml"
doc.bat
generování kompletní JavaDoc reference do adresáře docs

Jak používat systém Ant

JaGrLib repository nyní obsahuje i build.xml - script pro Apache Ant.
Ant lze použít pro automatické překládání, generování dokumentace a jiné úlohy, může nahradit řádkové příkazy. Pro instalaci a používání systému si přečtěte on-line manuál.

Nejčastěji používané příkazy:

ant compile
překlad knihovny JaGrLib bez ladicích informací (přeloží jen co je třeba)
ant debug
překlad knihovny JaGrLib s ladicími informacemi (přeloží jen co je třeba)
ant skel nebo jen ant
spuštění programu Skel (automaticky projekt přeloží, pokud je třeba)
Přidáním parametru -Dcomp=data/xxx.xml je možné přímo natáhnout sestavu xxx.xml do aplikace Skel
Zadáním parametru -Ddebug=-d se zapne ladicí režim (viz LogFile.debugging)
ant clean
smaže adresář class a způsobí tak kompletní překlad celé knihovny
ant jar
zabalí cílové soubory (.class) a nejpotřebnější data knihovny JaGrLib do archivu WWW/jagrlib.jar. Z tohoto archivu lze pohodlně spouštět aplikaci Skel
ant doc
vygeneruje ze zdrojových souborů knihovny JaGrLib JavaDoc referenci, výsledek uloží do adresáře docs a navíc zabalí do archivu WWW/docs.zip

Jak pracovat v prostředí Eclipse

Tomu se věnuje celá speciální stránka.

Instruktážní video: Práce s Eclipse 3.2 (starší verze) (49.8 MB).

Jak pracovat v prostředí NetBeans IDE

Tomu se věnuje celá speciální stránka.

Jak přidat do JaGrLib zcela nový modul

Tomu se věnuje také zvláštní stránka.

Jak řešit zápočtovou úlohu

Jenom základní schéma, jak si připravit prostor pro řešení zápočtové úlohy - předpokládám, že je předmětem úlohy jediný modul. Vždycky mějte při ruce konkrétní návod, např. úloha č. 41.

  1. příkazem "svn update" aktualizovat pracovní kopii JaGrLib na vašem lokálním disku
     
  2. v návodu identifikovat vzorový (triviální) modul a okopírovat ho s jiným jménem. Nezapomenout na pravidlo uvedené v zadání úlohy (např. modul "FractalCircles.java" uložit pod jménem "FractalJanKuchar.java")
     
  3. v novém modulu přepsat jméno třídy, aby souhlasilo se jménem souboru (např. "class FractalJanKuchar").
    Doporučuji též přepsat registrační jméno modulu (private final static String NAME = "FractalJanKuchar")
     
  4. nyní již lze nový modul v pořádku přeložit, můžete ho tedy např. přidat do Eclipse projektu (příkazem "Refresh" v příslušné package)
     
  5. pokud má mít nový modul jiné zásuvky než vzor, je potřeba změnit registraci zásuvek - viz funkce "public static int setTemplate ( Template t, int ord )".
    Pro registraci povinných zásuvek se používají metody "newInputPlug()" a "newOutputPlug()", pro registraci nepovinných zásuvek metody "newOptInputPlug()" a "newOptOutputPlug()"
     
  6. je-li potřeba přidat nové parametry, použijte samostatný návod
     
  7. program Skel se musí po přidáním (nebo i jakékoli změně) modulu přestartovat. Nezapomeňte před tím projekt přeložit
     
  8. jestliže začínáme s novým modulem ("FractalJanKuchar") pracovat nebo jsme změnili jeho registraci (zásuvky nebo parametry = properties), musíme modul zaregistrovat / přeregistrovat.
    Návod na registraci modulu:
    1. vybrat příkaz "Tools / Module Registration"
    2. na první řádce opravit jméno package, ve který se modul nachází ("cz.cuni.jagrlib.testing")
    3. stisknout tlačítko "Reg Files" (vpravo dole)
    4. vybrat si zdrojový soubor příslušného modulu ("FractalJanKuchar.java")
    5. (pokud provádíme opakovanou registraci, musíme potvrdit, že se má modul přeregistrovat)
    6. v dialogovém okně se automaticky vyplní všechny registrační položky, na závěr je třeba stisknout tlačítko"Save" a dialog opustit

     
  9. po úspěšné registraci nového modulu jej můžeme vložit do vzorového zapojení místo modulu původního:
    vybereme původní modul a zvolíme v lokálním menu příkaz "Replace Piece". Pak si zvolíme ze seznamu nový modul a potvrdíme tlačítkem "Ok"
    Upozornění: při nahrazování modulu s několika zásuvkami se stejným interface (např. "Pixelize", "OrderedDither") dochází při náhradě k popletení zásuvek. Je třeba ručně to zkontrolovat a přepojit.
     
  10. opravenou sestavu doporučuji uložit pod jiným jménem (příkazem "File / Save As.."). Tuto novou sestavu (třeba "data/sFractalJanKuchar.xml") si potom můžete přidat do command-line parametrů pro spouštění programu Skel (aby byl váš ladicí cyklus co nejkratší).

Instruktážní video: Řešení zápočtové úlohy (59.1 MB).

Jak přidat nový parametr (Property)

Návod na přidání nového parametru (property) do již existujícího modulu:

  1. přidat stavovou proměnnou (aktuální hodnota parametru) - např. 
    protected double scale = 1.0;
  2. zvolit si veřejné jméno parametru a deklarovat pro něj konstantu - např. 
    public final static String SCALE  = "Scale";
    Jméno je jednoznačný identifikátor parametru a bude se objevovat v GUI
     
  3. ošetřit nastavování a čtení parametru v metodách "set()" a "get()". Při nastavování lze použít knihovní funkce "intProperty()", "doubleProperty()", "enumProperty()", apod.
    Příklad nastavení parametru (uvnitř "set()", kontroluje se minimální přípustná hodnota 0.1 a maximální přípustná hodnota 10.0): 
    if ( key.compareTo(SCALE) == 0 )
{
  scale = doubleProperty( value, scale, 0.1, 10.0 );
  return;
}
    Příklad čtení parametru (uvnitř "get()"): 
    if ( key.compareTo(SCALE) == 0 )
  return exponent;
  4. doplnit registraci parametru - v metodě "setTemplate()" přidat registrační sekci ohraničenou "t.propBegin()" a "t.propEnd()".
    Nepovinně lze použít metody "t.propDefault()", "t.propBounds()", "t.propManipulator()" a v případě zadávání pomocí list-boxu "t.propEnum()".
    Dva příklady: 
    t.propBegin( SCALE, TYPE_DOUBLE, "Scale factor", true );
  t.propDefault( 1.0 );
  t.propBounds(  0.1, 10.0 );
t.propEnd();
    t.propBegin( TYPE, TYPE_INTEGER, "Colormap type", true );
  t.propDefault( ColormapType.CMAP_TRICOLOR.ordinal() );
  t.propManipulator( MANIPULATOR_COMBO );
  t.propEnum( "Gray ramp", ColormapType.CMAP_GRAY.ordinal(),     "Gray ramp (256 items)" );
  t.propEnum( "Tricolor",  ColormapType.CMAP_TRICOLOR.ordinal(), "Tricolor (192 items)" );
t.propEnd();
  5. po přeložení upraveného modulu je nutné přestartovat aplikaci Skel a modul přeregistrovat

I přidávání nového parametru a registraci modulu najdete na instruktážním videu: Řešení zápočtové úlohy (59.1 MB).

Užitečné konstanty a funkce

Používejte přednostně konstanty a rutiny definované v Java API a v knihovně JaGrLib. Budou pravděpodobně korektnější a rychlejší než vaše vlastní.
K okamžitému přístupu na dokumentaci Java 1.5 můžete použít tento odkaz. On-line dokumentaci knihovny JaGrLib si můžete vygenerovat sami příkazem doc.bat nebo použít potenciálně trochu zastaralou verzi na tomto serveru.

Java API:

Zejména bych chtěl upozornit na funkce z package java.lang:

Třída java.lang.System:
funkce na kopírování segmentů polí System.arraycopy()
funkce na měření času System.currentTimeMillis()
 
Třída java.lang.Math obsahuje spoustu užitečných matematických konstant a funkcí, např.:
Ludolfovo číslo Math.PI
goniometricé, cyklometrické a ostatní funkce známé z lepších kapesních kalkulaček
zaokrouhlovací funkce long Math.round(double), int Math.round(float), double Math.rint(double), double Math.floor(double), double Math.ceil(double)
minima a maxima int Math.min(int,int), int Math.max(int,int) + varianty pro všechny ostatní numerické typy
převody mezi stupni a radiány double Math.toDegrees(double) a double Math.toRadians(double)
přímý výpočet přepony pravoúhlého trojúhelníka double Math.hypot(double,double)
 
Třídy z package java.util implementují mnoho užitečných kontejnerů: dynamická pole, seznamy, množiny, hašovací tabulky, ..
 
Třída java.util.Arrays obsahuje funkce pro práci s poli (inicializace, třídění, porovnávání, ..)

Externí knihovny:

Knihovna na vyhodnocování výrazu JEP: můžete si přečíst jednoduchý návod nebo použít rovnou JavaDoc referenci.
Pro usnadnění můžete použít podpůrnou funkci Formula.initExpression(String)

Knihovna JaGrLib:

Pár obecně užitečných tříd je umístěno přímo v package cz.cuni.jagrlib:

Třída cz.cuni.jagrlib.Formula obsahuje například:
zaokrouhlení z typu double přímo do int Formula.round(double)
omezení vstupní hodnoty daným minimem a maximem Formula.clamp(int,int,int) + varianty pro všechny ostatní numerické typy
barevné převody Formula.colorRamp(double,double[]), Formula.RGBToRGBe(byte[],int,double,double,double), Formula.rgbToGray(double,double,double) + varianty pro některé ostatní numerické typy, Formula.rgbToHsv(double,double,double,double[]), Formula.hsvToRgb(double,double,double,double[]),
VLC kódování a dekódování: Formula.vlc(int) a Formula.vlcInv(long)
...
 
Třída cz.cuni.jagrlib.Geometry obsahuje konstanty a funkce, které mají nějakou souvislost s geometrií, např.:
skalární a vektorové součiny Geometry.dotProduct3D(double[],double[]) a Geometry.vectorProduct(double[],double[],double[])
výpočty vzdáleností, např.: Geometry.pointPoint3D(double[],double[]), Geometry.pointSegment2D(double[],double[],double[]), Geometry.pointSegment3D(double[],double[],double[]), Geometry.pointBox2D(double[],double[],double[]), Geometry.pointBox3D(double[],double[],double[])
test bod versus trojúhelník Geometry.pointInTriangle2D(double[],double[],double[],double[],double[])
hledání kolmých vektorů v 3D Geometry.getPerpendiculars(double[],double[],double[])
...
 
Třída cz.cuni.jagrlib.Complex obsahuje implementaci komplexních čísel
 
Třída cz.cuni.jagrlib.TrMatrix obsahuje operace s transformačními maticemi ve 2D, 3D (kartézské i homogenní varianty)
 
Třída cz.cuni.jagrlib.RandomStatic obsahuje některé slavné pseudo-náhodné generátory (dají se použít i pro hashovací účely)
 
Třída cz.cuni.jagrlib.RandomJames obsahuje velmi kvalitní náhodný generátor F. Jamese
 
Třída cz.cuni.jagrlib.IntMap<T> obsahuje implementaci efektivní hašovací mapy indexované celými čísly

Ladění, log-files

JaGrLib má pro potřeby ladění vestavěný mechanismus zápisu log-file. Vše je soustředěno uvnitř třídy cz.cuni.jagrlib.LogFile. Textové výstupy se zapisují do souboru v aktuálním adresáři log.txt. Obrazové výstupy jsou zcela pod kontrolou uživatele = programátora.

Textové výpisy:
LogFile.log(String) vypisuje zadaný řetězec
LogFile.debug(String) vypisuje zadaný řetězec jenom pokud je zapnutý ladicí režim (command-line parametr "-d")
LogFile.exception(Exception) vypisuje informace o dané výjimce
LogFile.stackTrace(String) vypisuje okamžitý obsah zásobníku
...
 
Obrazové výstupy:
LogFile.createImage( int width, int height, int mode, String fileName ) zakládá nový obrázek, jehož handle můžeme dále používat v metodách:
LogFile.getImage( int id ) vrací RasterGraphics objekt, do kterého lze kreslit
LogFile.saveImage( int id ) ukládá aktuální stav obrázku do souboru
LogFile.closeImage( int id ) ruší daný obrázek (bez jeho uložení!)
 
"Sondy":
Třída LogFile umožňuje při běhu programu načítat textové soubory obsahující definice proměnných - tzv. "sondy" (probes).
LogFile.readProbe( String fileName ) načte definice proměnných do aktuálního prostředí, odkud se potom dá číst metodami jako např.:
int LogFile.intProperty( String key, int def ), double LogFile.doubleProperty( String key, double def ), boolean LogFile.booleanProperty( String key, boolean def ),
...

Jak vyrobit animaci

Pokud v systému JaGrLib vytvoříte posloupnost obrázků (třeba pomocí worker-modulu cz.cuni.jagrlib.worker.AnimationWorker), potřebujete z nich vyrobit animaci - např. ve formátu MPEG-4 uloženou do AVI souboru.

K tomu doporučuji použít řádkový program ffmpeg, který se snadno ovládá a umí používat populární MPEG-4 kodeky. Stáhnout binární verzi můžete například zde. Jediným vyvoláním programu vyrobíme z posloupnosti rastrových obrázků AVI animaci:

  1. pokud vaše verze ffmpeg neumí přímo načítat PNG obrázky vyrobené knihovnou JaGrLib, je potřeba je zkonvertovat - např. programem IrfanView.
    IrfanView obsahuje příkaz File / Batch Conversion/Rename (shortcut "B"). Po jeho vyvolání je potřeba vybrat všechny konvertované soubory, přesunout je do levé části okna a vpravo zadat "Batch conversion" a správně nastavit cílový adresář a výstupní formát (doporučuji "PPM - Portable Pixelmap").
    Nakonec se dávka spustí tlačítkem "Start"..
  2. příkazová řádka pro vyvolání programu ffmpeg může vypadat třeba takto:
    ffmpeg -i out%04d.png -f avi -vcodec msmpeg4v2 -qscale 2 -y out.avi
    Seznam všech parametrů dostanete zadáním ffmpeg -h, seznam použitelných kodeků zadáním ffmpeg -formats (doporučuji používat kodeky msmpeg4v2, xvid nebo mpeg)
    Příklad batche pro kódování videa (pro menší bitrate můžete zvětšit hodnotu uvedenou v parametru "-qscale q")

Podpora OpenGL

JaGrLib obsahuje podporu programování real-time grafiky pomocí OpenGL. Volání OpenGL API zajišťuje externí knihovna JOGL, jejíž vývoj je podporován firmou SUN.

Instalace OpenGL podpory

Pro překlad projektu je vše potřebné již zahrnuto v JaGrLib repository. Stačí pracovat s atuální verzí projektu a používat některý podporovaný build-systém (řádkové příkazy, systém Ant, Eclipse IDE nebo NetBeans IDE). Pokud potřebujete spustit některý modul pracující s OpenGL, musíte doinstalovat několik run-time knihoven. Postupujte takto:

  1. v souboru lib/JOGL-version.txt si přečtěte použitou verzi JAR knihoven (např. 1.1.1-rc6)
  2. navštivte WWW stránky projektu JOGL a stáhněte si instalaci odpovídající vašemu operačnímu systému a procesoru (např. jogl-1.1.1-rc6-windows-i586.zip)
  3. z archivu okopírujte všechny dynamické knihovny (.dll, .so, .jnilib, apod.) do adresáře lib
Stručný návod je též obsažen v textovém souboru lib/README-opengl.txt.

Test OpenGL

V repository je několik sestav používajících OpenGL. Jejich spuštěním můžete zkontrolovat, že je instalace v pořádku:

[JaGrLib home-page]  [CGG at MFF UK]

Valid XHTML 1.1 Copyright (C) 2006-2009 J.Pelikán, last change: $Date: 2013-11-22 23:47:16 +0100 (Fri, 22 Nov 2013) $
Send comments/requests to pepca.at.cgg.mff.cuni.cz