En dokumentation om Java 3D API

En dokumentation om Java 3D API Johan Pellbäck Inst för Data- och Systemvetenskap Stockholms Universitet

1. INLEDNING... 1 1.1. VAD ÄR JAVA 3D API?... 1 1.2. EN VIRTUELL, 3-DIMENSIONELL VÄRLD... 1 1.3. EN HIERARKI AV KLASSER... 2 1.4. BESKRIVNING AV ETT ANTAL ANVÄNDBARA KLASSER... 3 2. NÅGRA KODEXEMPEL... 3 2.1. SKAPA ETT VIRTUELLT UNIVERSUM... 3 2.2. KOPPLA SAMMAN DITT UNIVERSE MED EN BRANCHGROUP... 4 2.3. ATT SKAPA RÖRELSE... 4 3. INSTALLATION OCH MILJÖ... 5 3.1. INSTALLERA JDK... 5 3.2. INSTALLERA JAVA3D 1.3.1, DIRECTX... 6 3.3. TIPS OCH TRIX... 6

1. Inledning Detta dokument har till syfte att ge en inblick i funktionerna och användandet av Java 3D API. Förhoppningen med dokumentet är att minska tröskeln för studenter som snabbt vill komma igång med 3D-programmering och att ge en snabb överblick över de olika klasserna och hur de samarbetar. Dokumentet innehåller också en installationsanvisning och några kommentarer till vad man bör tänka på vid installation och exekvering av sina Java-program. Erfarenheterna, som ligger till grund för detta dokument, baserar sig på Java 3D version 1.3.1 och operativsystemet Windows 2000. 1.1. Vad är Java 3D API? Java 3D är utvecklat av Sun Microsystems som ett standardtillägg till Java 2 SDK. Det är alltså ett API med klasser som tillhandahåller funktionalitet för att skapa, manipulera och rendera 3 dimensionella geometriska objekt. 1.2. En virtuell, 3-dimensionell värld Att presentera ett 3-dimensionellt objekt på en 2-dimensionell yta, som datorns skärm faktiskt är, innebär i realiteten att man manipulerar med färg, ljus och form för att vårt öga skall uppfatta objektet i 3 dimensioner. För att få en konceptuell bild av det hela kan vi se det som att våra geometriska objekt existerar i två världar. Dels ett virtuellt 3-dimensionellt universum som beskriver våra geometriska objekt i 3 riktningar (X, Y, Z), detta kan vi inte riktigt avbilda på vår datorskärm. Dels en 2-dimensionell färgduk på vilken våra bilder av den virtuella världen projiceras, denna projicering kallas för rendering. I Java 3D API beskrivs dessa två miljöer som Virtual Universe och Image plate. Figur 1 en konceptuell bild av Image plate och Virtual Universe 1

1.3. En hierarki av klasser Vårt 3-dimensionella universum, som vi nu kallar för scen, byggs upp med klasser ur Java 3D API i en sorts hierarki. Relationen dessa emellan bygger på konceptet parentchild där en nod i hierarkin kan ha flera childs men bara en parent. En leaf-node kan ha en parent men inga childs. Vår scen utgår från en root och det finns bara en väg genom grafen från root till varje leaf-node. Skall man vara noggrann så bör det tilläggas, eftersom det bara finns en enda väg från root till leaf-node, att det också finns en scen för varje leaf-node. VirtualUniverse <<extend>> <<reference>> Canvas3D SimpleUniverse - canvas: Canvas3D SceneGraphObject <<abstract>> Node BranchGroup Group <<abstract>> <<parent, child>> + addchild() : void + getchild() : Node TransformGroup TransformGroup - transform: Transform3D Transform3D + rotx() : void + roty() : void + rotz() : void BoundingSphere Shape3D <<Text2d etc.>> Primitive <<Box, Cone, Cylinder etc. >> RotationInterpolator - tg: TransformGroup - bs: BoundingSphere - transform: Transform3D + setschedulingbounds(boundingsphere) : void + setaxisofrotation(transform3d) : void Figur 2 Klassdiagram Figur 2 visar en exemplifiering av ett virtuellt universum med klassen SimpleUniverse som root och klassen Canvas3D som Image plate. Ett virtuellt universum består i sin grundläggande del av två kategorier objekt, VirtualUniverse och SceneGraphObject. VirtualUniverse bildar root-objektet och fungerar som hållare av den 3-dimensionella scenen. SceneGraphObject består i sin tur av kategorierna Node och Group vilka utgör de vanligaste objekten i scenen. SceneGraphObject och Node är abstrakta klasser som definierar ett antal grundläggande metoder och attribut för sina subklasser. Group, här exemplifierade som BranchGroup och TransformGroup, är klasserna som specificerar och har ansvar för placering och form av visuella objekt i grafen. Detta var en grov beskrivning av generella klasser, de övriga klasserna i figur 2 beskrivs nedan. 2

1.4. Beskrivning av ett antal användbara klasser Canvas3D denna klass är en gränssnittskomponent (UI component) och ärver sina egenskaper från komponenter ur AWT (Abstract Windowing Toolkit). Den används för att rendera 3D objekt. BranchGroup denna klass används för att skapa 3D-scenens hierarki. En BranchGroup klass hålls av en VirtualUniverse klass och kan ha flera childs. TransformGroup denna klass ingår också i 3D-scenens hierarki och är child till BranchGroup. Den ansvarar vanligtvis för transformering av objekt, exempelvis rotering, detta genom att hålla en referens till ett Transform3D objekt. Transform3D denna klass ingår inte i scenens hierarki men används av TransformGroup för att transformera grafiska objekt, exempelvis genom att rotera en figur i någon riktning. När man specificerar en transformation, exempelvis en rotering, så gör man det i radianer. Cone denna klass ingår i ett paket med geometriska objekt. Den specificerar en kon med radie och höjd. ColorCube - ett geometriskt objekt som specificerar en kub med sidor i olika färger. RotationInterpolator en klass som sammankopplas med TransformGroup och Transform3D för att skapa rörelse hos geometriska objekt. Alpha en klass som används för att definiera variationer i tiden. BoundingSphere en klass som används för att definiera en gräns/region med hjälp av ett centrum och en radie. 2. Några kodexempel 2.1. Skapa ett virtuellt universum För att kunna köra sin 3D-rendering i både en webb-läsare (som applet), genom appletviewer eller som en separat Java-applikation kan det vara bra att först skapa en klass som är subklass till Applet. Denna klass implementerar en main-metod som använder sig av en MainFrame där man startar sin applet. import com.sun.j3d.utils.applet.mainframe; public class Exempel3D extends Applet { public Exempel3d{ publid static void main(string[] args{ Frame frame = new MainFrame(new Exempel3D(), 256, 256); Kodexempel 1 Klassdeklaration och main-metod Skapa sedan ett VirtualUniverse, ett Canvas3D för rendering och en BranchGroup i kontruktorn på din Applet klass. Canvas3D objektet kräver en instans av klassen GraphicsConfiguration vid instansiering, skapa denna klass genom att anropa den statiska metoden gerpreferredconfiguration i SimpleUniverse klassen. 3

public Exempel3d{ GraphicsConfiguration config = SimpleUniverse.getPreferredConfiguration(); canvas3d = new Canvas3D(config); this.add("center", canvas3d); su = new SimpleUniverse(canvas3D); su.addbranchgraph(makebranchgraph()); setsize(300,300); Kodexempel 2 konstruktorn 2.2. Koppla samman ditt Universe med en BranchGroup I exemplet ovan skapas BranchGroup i en separat metod, makebranchgraph(). Låt denna metod skapa en BranchGroup med underliggande TransformGroup, eventuella geometriska objekt och ett Transform3D objekt som ansvarar för transformation av de geometriska objekten. private BranchGroup makebranchgraph(){ BranchGraph returnobj = new BranchGraph(); Transform3D rotor1 = new Transform3D(); Transform3D rotor2 = new Transform3D(); rotor1.rotx(math.pi/4.0d); rotor2.roty(match.pi/5.0d); rotor1.mul(rotor2); TransformGroup tg = new TransformGroup(rotor1); tg.addchild(new ColorCube(0.4)); returnobj.addchild(tg); return returnobj; Kodexempel 3 skapa Branchgroup Exemplet ovan skapar två olika Transform3D objekt, detta har effekten att kuben i detta exempel kommer att kunna rotera i två olika riktningar (X-led och Y-led). 2.3. Att skapa rörelse Att skapa rörelse i sin 3-D scen kan göras på många sätt. Som programmerare kan man välja att använda inbyggda beteenden och rörelsemönster hos objekten eller helt och hållet definiera egna. Beteendet hos objekten kan antingen definieras som en interaktion med användaren eller automatiskt utsträckt i tiden. Med hjälp av klassen RotationInterpolator kan man använda sig av de inbyggda beteenden som tillhandahålls i Java 3D API. Med hjälp av en tidsfunktion uppdaterar klassen automatiskt ett eller flera objekt i scenen. Med hjälp av en Transform3D, som skapats inom en TransformGroup, kan ett RotationInterpolator objekt manipulera alla de underliggande objekt som är underliggande childs till en viss TransformGroup. RotationInterpolator använder sig av klassen Alpha för att kunna bestämma ett beteende i tiden. Denna klass är komplex och någon ingående beskrivning av klassen ges inte här. 4

private BranchGroup makebranchgraph(){ Alpha alpha = new Alpha(-1, Alpha.INCREASING_ENABLE, 0, 0, 5000, 0, 0, 0, 0, 0); RotaionInterpolator ri = new RotationInterpolator(alpha, tg); ri.setaxisofrotation(rotor1); Kodexempel 4 använding av RotationInterpolator och Alpha I ett virtuellt universum kan det tänkas att man definierar flera olika beteenden och kopplar dessa till flera olika objekt. Det finns då en risk för att systemet snabbt blir överbelastat. Därför är det bra att definiera en gräns eller region för en RotaionInterpolator, en BoundingSphere. private BranchGroup makebranchgraph(){ BoundingSphere bounds = new BoundingSphere(new Point3d(0.0, 0.0, 0.0), 100.0); ri.setschedulingbounds(bounds); Kodexempel 5 använding av BoundingSphere Det finns mycket mer att fördjupa sig i angående rörelsebeteende, manipulation och interaktion med 3D-objekt. Denna dokumentation har dock inte för avsikt att gå särskilt djupt in på detta område, för en djupare genomgång hänvisas till dokumentation om Java 3D API. 3. Installation och miljö För dig som har tänkt att installera, programmera och köra Java 3D rendering på en egen dator kommer här en liten installationsanvisning samt några tips att tänka på innan du kör igång. 3.1. Installera JDK Om du inte sedan tidigare har JDK installerat på din dator bör du börja med att installera detta. Ladda hem senaste versionen från http://java.sun.com/downloads/. Lämpligtvis väljer du att installera Java 2 Standard Edition (J2SE). Var noga med att installera SDK (Software Development Kit) och inte bara JRE (Java Runtime Environment). När installationen är klar kan du verifiera att allting fungerar genom att starta kommandofönstret (Start run cmd) och skriva. java version. Detta kommando visar vilken version av JDK som installerats och indikerar att ditt system hittar javatolken. Ett bra tips är att lägga till en punkt (.) till CLASSPATH, detta betyder att aktuell katalog alltid inkluderas i Javas sökväg. CLASSPATH inställningen är åtkomlig i Windows under System Properties och Environment Variables. Genom att via kommandoprompten köra kommandot SET kan du se dina olika miljöinställningar på systemet. 5

3.2. Installera Java3D 1.3.1, DirectX Börja med att ladda hem programfilerna för Java 3D från Sun s hemsida. Dessa hittar du under http://java.sun.com/products/java-media/3d/. Var noga med att välja Java 3D for Windows (DirectX Version) SDK for the JDK (includes runtime). Starta installationen och se till att installera programpaketet på samma ställe som du tidigare installerat JDK. Om du installerar i samma bibliotek behöver du inte manipulera med CLASSPATH inställningarna på din dator. Ladda även hem API dokumentationen för Java 3D 1.3.1. Denna finner du under http://java.sun.com/products/java-media/3d/download.html. Denna laddas ner som en ZIP eller TAR och kräver därför WinZip. Packa upp denna fil i något lämpligt bibliotek på din dator. Du kommer att ha mycket nytta av att läsa API dokumentationen. Nu kan du verifiera att Java 3D fungerar genom att exempelvis köra något av de exempel som följer med installationen. Starta kommandofönstret och leta dig fram till JDK katalogen (exempelvis: cd\jdk\jdk1.4.0_01). Ställ dig i någon av katalogerna demo (exempelvis: cd demo\java3d\appearance). Prova att starta ett exempel med hjälp av AppletViewer (exempelvis: appletviewer AppearanceTest.html). 3.3. Tips och trix Testköra applikationer Det kan vara ganska knepigt att få applikationerna att fungera i alla olika miljöer och webbläsare. Ett bra tips är att under utvecklingsfasen bara köra koden i appletviewer. Då slipper du onödiga felkällor som kan uppstå i din webbläsare, dessa problem är bättre att tampas med när koden börjar bli färdig. Ett annat tips vid testning är att köra sin applet i com.sun.j3d.utils.applet.mainframe. Då kan du under testfasen köra din kod i en vanlig java-applikation (se i exempelkoden i detta dokument). Inställningar i webbläsaren Om du har problem med att få din kod att fungera i webbläsaren så bör du först och främst provköra exemplen som installeras tillsammans med Java 3D API. Peka din webbläsare till den katalog där du tidigare installerat Java 3D API, exempelvis file:// C:\jdk\jdk1.4.0_01\demo\java3d\index.html. Var säker på att du alltid har den senaste versionen av JDK installerat. Kontrollera efter uppdateringar på Suns hemsida: http://java.sun.com/products/plugin/ Undvik att installera JDK och Java 3D API i en katalog som innehåller blanksteg, exempelvis C:\Program Files\Java. En del 3D-program kommer att kräva en större heap-size. Prova att ändra denna inställning genom att lägga till parametern mx64m till körtidsparametrarna i kontrollpanelen för Java i Windows kontrollpanel. 6