SLOVENSKÁ TECHNICKÁ UNIVERZITA FAKULTA INFORMATIKY A INFORMAČNÝCH TECHNOLÓGIÍ ILKOVIČOVA 3, 842 16 BRATISLAVA 4 TÍM 13 SIMULÁCIA DEMONŠTRÁCIE V MESTE DEVELOPERSKÁ PRÍRUČKA Vedúci projektu: Ing. Ivan Kapustík Bc. Britvík Andrej (SI) Predmet: Tímový projekt Bc. Dupaľ Martin (IS) Ak. Rok: 2012/2013 Bc. Gomola Matej (IS) Kontakt: timovyprojekt13@gmail.com Bc. Králik Gergely (SI) Bc. Michalec Peter (IS) Bc. Ogurčák Filip (IS) Bc. Palát Peter (SI)
OBSAH ÚVOD... 1 ÚČEL A ROZSAH DOKUMENTU... 1 PREHĽAD DOKUMENTU... 1 OPIS KOMPONENTOV... 2 OPIS MODULOV V PROJEKTE... 3 MODULE MAP... 3 BEHAVIOUR MODULE... 5 IBEHAVIOURMODEL... 5 DEFAULTDECISSIONPROCESSER... 5 ACTION MODULE... 6 ABSTRACTACTION... 6 ACTIONMAP... 7 ACTIONEXPLORER... 7 PROGRAMOVANIE AKCIÍ... 8 ATTRIBUTE MODULE... 9 ABSTRACTATTRIBUTE... 9 IATTRIBUTEMODEL... 9 DEFAULTATTRIBUTESMODEL... 11 PRIDÁVANIE ATRIBÚTOV... 11 MESSAGE MODULE... 12 GEOMETRY MODULE... 15 PATHPLIESKANICA... 15 GRAPHPLIESKANICA... 16 WAYPOINTPLIESKANICA... 17 OBSTACLEPLIESKANICA... 19 DRAWING MODULE... 21 ZVYŠNÉ MODULY... 23 IACCESSMAP... 23 IRANDOMGENERATOR... 23
ÚVOD Tento dokument vznikol v rámci predmetu Tímový projekt na Fakulte Informatiky a Informačných Technológií na Slovenskej Technickej Univerzite v Bratislave. Vypracoval ho STEAM (tím 13) v akademickom roku 2012 / 2013. Náš tím sa zaoberal simuláciou demonštrácie v meste. ÚČEL A ROZSAH DOKUMENTU Účelom tohto dokumentu je opísať základné koncepty jednotlivých komponentov, v ktorých sa nachádzajú jednotlivé modul. Tento dokument tak isto obsahuje slovný opis základných rozhraní, ktorý je obohatený o obrázky. Zvyšný opis jednotlivých funkcií nie je uvádzaný, lebo buď je názov metódy dosť sebavysvetľujúci, alebo sa nachádza v javadocu konkrétnych tried alebo rozhraní v projekte. PREHĽAD DOKUMENTU Dokument pozostáva z nasledujúcich častí: Opis komponentov opisuje základné komponenty v projekte Opis modulov v projekte opis modulov v projekte Behaviour module opis modulu, ktorý implementuje správanie Action module opis modulu na vykonávanie akcií agentov Attribute module opis modulu na reprezentáciu atribútov agentov Message module opis modulu na komunikáciu medzi agentami Geometry module opis modulu na prácu s geometrickými funkciami Drawing module opis modulu na kreslenie Zvyšné moduly menej dôležité moduly 1
OPIS KOMPONENTOV V zdrojových kódoch sa nachádzajú štyri komponenty. Core Middle Surface Utils Závislosti týchto projektov sú zobrazené na obrázku Obrázok 1. Obrázok 1 - závislosti projektov V projekte Core sa nachádzajú definície základných rozhraní, ktoré sa v projekte využívajú. Dôvodom vytvorenia tohto a týchto rozhraní bolo definovať istý štandard, pomocou ktorého by bolo možné zjednodušiť vývoj celej simulácie. V projekte Middle sú implementácie týchto rozhraní. Tento projekt má tvoriť stred medzi projektami Core a Surface. Surface je druhý výrazný projekt v simulácií. Sú v ňom triedy, ktoré sú priamo závislé od knižníc ako je napríklad RVO a Mason. Týmto štýlom nás pri implementácií rozhraní v projekte Middle nemusí trápiť aké knižnice sa využívajú v projekte Surface, lebo existujú rozhranie v projekte Core, ktoré ich obaľujú. Podrobnejší popis toho, ako je toto dosiahnuté sa nachádza v neskorších kapitolách. 2
OPIS MODULOV V PROJEKTE Vzhľadom na komplexnosť modelu ľudského správania sme vytvorili niekoľko modulov, ktoré sú navzájom vymeniteľné. Jedná sa o nasledujúce moduly: Access modul Action modul Attribute modul Behaviour modul Message modul Geometry modul Drawing modul Závislosti medzi jednotlivými modulmi sú zobrazené na obrázku Obrázok 2. Obrázok 2 - závislosti medzi modulmi Bližší opis jednotlivých modulov sa nachádza v nasledujúcich kapitolách. MODULE MAP V projekte Core je najdôležitejším prvkom trieda ModuleMap, ktorá je singleton zdieľaný pre celú simuláciu. Práve v tejto triede sa nachádzajú referencie na najdôležitejšie rozhrania v projekte. Medzi tieto rozhrania patria najmä: 3
IAccessMap - Access module IBehaviourModel - Behaviour module IMessageModule - Message module IAttributeModel - Attribute module Nenachádza sa tu referencia na nasledujúce moduly: Action module Drawing module Geometry module Rozhrania tried v týchto moduloch sú totiž singleton-y. Bolo by vhodnejšie ich vložiť tiež do Module mapy, ale v rámci nášho tímového projektu na to nezvýšil čas. Existuje niekoľko default-ných implementácií týchto rozhraní, ktoré sa inicializujú na začiatku. Jedná sa najmä o: IBehaviourModel - DefaultDecissionProcesser IMessageModule - DefaultMessageModule IAttributeModel - DefaultAttributesModel IRandomGenerator - DefaultRandomGenerator Tieto je možné potom zmeniť pomocou set metód triedy ModuleMap. Napríklad pri spustení simulácie, počas inicializácie sa spúšťa tento kód: ModuleMap.setRandomGenerator(new MasonRandomGenerator()); Vďaka tomu je možné vo všetkých projektoch využívať triedu MasonRandomGenerator, ktorá využíva knižnicu Mason na generovanie náhodných čísel. Existuje aj trieda DefaultRandomGenerator, ktorá generuje náhodné čísla pomocou systémovej knižnice javy. Obrázok Obrázok 3 znázorňuje postupnosť vykonávania krokov v simulácií. Obrázok 3 - postupnosť vykonávania 4
BEHAVIOUR MODULE Behaviour module je zodpovedný za správanie agentov. Najdôležitejším prvkov tohto modulu je rozhranie IBehaviourModel. Existuje niekoľko rôznych modelov správania človeka, preto sme sa rozhodli nechať tento prvkov konfigurovateľný IBEHAVIOURMODEL Úlohou tohto rozhrania je vykonávať akcie. Momentálne rozhranie IBehaviourModel predpisuje len jednu metódu: void makechoiceofaction(iattributemodel atributes, long agentid) Metóda vracia void, kvôli tomu, aby nebolo možné ovplyvňovať rozhodnutia mimo tento modul. Viac o akciách napísané v nasledujúcej kapitole. DEFAULTDECISSIONPROCESSER Trieda DefaultDecissionProcesser implementuje rozhranie IBehaviourModel. Jej referencia na ňu sa ukladá do ModuleMap, ktorú je potom možno zmeniť. Vykonávanie predpísanej metódy makechoiceofaction je veľmi jednoduché. V metóde sa vyčlenia vykonateľné akcie na záver sa vyberie jedna akcia, ktorá sa vykoná. Takéto rozhodovanie nezodpovedá modelu ľudského správania PECS, v ktorej sa vždy vyberá akcia podľa najsilnejšieho atribútu. 5
ACTION MODULE Pod akciou sa chápe neelementárna činnosť, čo môže agent vykonávať. Napríklad strieľanie, alebo vytláčanie davu. Action Module pozostáva z rozhrania pre jednotlivé akcie a dátovej štruktúry, ktorá obsahuje všetky zoznam všetkých používaných akcií. Základný koncept Action Module je zobrazený na obrázku Obrázok 4. Obrázok 4 - Koncept Action Module-u ABSTRACTACTION Myšlienkou actionmodule v projekte je vytvoriť rozhranie, ktoré by urýchľovalo písanie jednotlivých akcií. Za týmto účelom sme vytvorili triedu AbstractAction. Táto trieda predpisuje nasledujúce metódy: void executed(long agentidfrom) void activated(message message) boolean isok(long agentid) double getchance(long agentid) int getneededsteps(long agentid) Metóda executed by sa mala vykonávať v tele funkcie makechoiceofaction, ktorú predpisuje rozhranie IBehaviourModel. Metóda activated by sa mala vykonať len v prípade, že sa pošle v správe inému agentovi. Viac informácií v časti MessageModule Metóda isok, určuje, či je možné vykonať akciu. Metóda getchance, určuje číselnú mieru pravdepodobnosti vykonania akcie. 6
Metóda getneededsteps, určuje koľko krokov sa má konkrétna akcia vykonávať. Preddefinovaná hodnota je nula, ale je možné ju zmeniť override-nutím tejto metódy. Jednotlivé akcie sú implementované v module Middle. Všetky akcie sú uložené v triede ActionMap, ktorá je opísaná v nasledjúcej kapitole. ACTIONMAP Táto trieda predstavuje singleton, v ktorom je uložená mapa všetkých akcií pre konkrétnu simuláciu. Na začiatku sa načítajú všetky akcie. Toto načítanie umožňuje knižnica reflections, ktorá pomocou reflection-nov dokáže získať referencie na objekt Class všetkých tried, ktoré dedia od triedy AbstractAction. Následne je možné z tejto triedy odstraňovať nežiadúce akcie. Napríklad v prípade editora, v prípade, že niektoré akcie nie sú zvolené, tak sa jednoducho z tejto štruktúry odstránia počas inicializácie simulácie. ACTIONEXPLORER Kvôli udržaniu prehliadnosti jednotlivých volaní framework-u v akciách sme vytvorili nástroj, ktorý umožňuje rýchly prístup k týmto informáciam. Nástroj sa nazýva ActionExplorer. Na vstupe vyžaduje adresár, v ktorom sú uložené všetky triedy akcií. Tento vstup sa zadáva ako parameter metódy processfolder(file dir). Ideálne by bolo dorobiť GUI, ale nebol na to čas. Výstupom tohto nástroja je text, ktorý sa vypíše na konzolu, ktorého štruktúra je zobrazená nižšie na obrázku Obrázok 5. Nástroj vypisuje na prvej úrovni všetky triedy na prvej úrovni. Na druhej úrovni vypisuje všetky metódy triedy. Na ďalších úrovniach vypisuje zistené údaje. Napríklad na zobrazenom príklade zobrazuje, že v triede Punch v metóde executed sa posielajú správy, ktoré obsahujú akciu s názvom NAME. Táto správa tak isto obsahuje detaily neighbourid a stop. O niekoľko riadkov nižšie je vidieť, že táto trieda v metóde activated získava tieto detaily, ktoré sú typu Long a Boolean. Tento nástroj slúži na uľahčenie hľadania chýb pri písaní akcií. Tento nástroj nie je plne otestovaný. Otestovali sme ho len na niekoľkých akciách. Tak isto jeho kód nie je najlepší a v prípade ďalšieho rovoja by bolo potrebné ho zlepšiť. Nástroj funguje na základe parsovania XML zdrojového kódu. Toto XML získavame pomocou open source nástroja srcml, ktoré vytvára z java zdrojových kódov štruktúrované XML súbory. Následne náš nástroj pomocou XPath výrazov získava jednotlivé potrebné informácie. 7
In class Punch In method executed SendMessageArguments: NAME SendMessageDetails: NAME = "neighbourid" - neightbors.get(0) NAME = "stop" - false In method activated SendMessageArguments: PunchReaction movefast SendMessageDetails: PunchReaction = "Damage" - damage GetDetails: "neighbourid" = Long "stop" = Boolean ChangeAttribute: Health = 0 GetAttribute: Strength Stamina Health In method getloginfo In method isok In method getactionname In method getchance Obrázok 5 - výstup z ActionExplorer-a PROGRAMOVANIE AKCIÍ Na naprogramovanie novej akcie stačí splniť nasledujúce kroky: Vytvoriť novú triedy Dediť túto triedu od abstraktnej triedy AbstractAction Implementovať predpísané metódy Kvôli efektívnejšej práci s akciou odporúčame do každej akcie doplniť nasledujúci riadok kódu: public static final String NAME = getunieuqname(#akcia#.class); Kde #AKCIA# predstavuje názov triedy akcie. Vďaka tomu je možné následne jednoducho získavať akciu z ActionMap. Ako bolo napísane v predošlej kapitole ActionMap, tak nie je potrebné dopisovať ďalší kód. Takto vytvorená akcia je pripravená na použitie. Pri implementácií akcie, môže programátor využívať ďalšie moduly, ktoré sú bližšie opísané v nasledujúcich kapitolách. 8
ATTRIBUTE MODULE V našom projekte sa pod pojmom atribút myslí akýkoľvek atribút agenta. V našej implementácií sa nachádzaju len emócie a fyzické vlastnosti, ale je to myslené na všetky možné atribúty ako môže byť aj motív násilia a podobne. Základný koncept Action Module je zobrazený na obrázku Obrázok 6Obrázok 4. ABSTRACTATTRIBUTE Na uľahčenie vytvárania nových atribútov sme opäť vytvorili abstraktnú triedu AbstractAttribute, ktorá predpisuje niekoľko základných metód, ktoré slúžia na spracovávanie atribútov. Tieto métody sú bližšie opísane v javadocu. Dôležité je, že táto trieda obsahuje definíciu atribútov: value maxvalue minvalue resistance Následne predpísané metódy tejto abstraktnej triedy slúžia na prácu s týmito atribútmi. IATTRIBUTEMODEL Vzhľadom na to, že môže existovať veľa rôznych atribútov, nie každý agent musí obsahovať všetky atribúty. Kvôli tomuto existuje rozhranie IAttributeModel, ktoré predpisuje niekoľko metód na prácu s atribútmi. Každý agent má vlastnú inštanciu implementácie tohto rozhrania, lebo každý agent nadobúda počas simulácie rôzne hodnoty jednotlivých atribútov. Svojím spôsobom je možné povedať, ze IAttribudeModel ponúka rozhranie, ktoré slúži na prácu s kolekciou atribútov. Nie je predpísaný žiadny spôsob ako sa má vytvárať kolekcia atribútov. Momentálne sa v DefaultAttributesModel využíva reflections na získavanie všetkých tried, ktoré implementujú abstraktnú triedu AbstractAttribute. 9
Obrázok 6 - koncept Attribute modulu 10
DEFAULTATTRIBUTESMODEL Trieda DefaultAttributesModel predstavuje implementáciu rozhrania IAttribudeModel. Myšlienkou tejto triedy je vytvoriť triedu, ktorá by poskytovala rozhranie pre prácu s atribútmi. Narozdiel od ActionMap existuje pre každého agenta jedinečná implementácia rozhrania IAttribudeModel. Defaultne sa nastavuje DefaultAttributesModel, ale je možné ho zmeniť. Princíp tejto triedy je nasledovný: Pred inicializáciou, pomocou reflection získať všetky triedy, ktoré dedia od AbstractAttribute Pri inicializácií tejto triedy, vytvoriť inštancie tried, ktoré dedia AbstractAttribute Zaradiť inicializované triedy do HashMap-y PRIDÁVANIE ATRIBÚTOV Na naprogramovanie novej akcie stačí splniť nasledujúce kroky: Vytvoriť novú triedu, ktorá dedí od abstraktnej triedy AbstractAction Implementovať predpísané metódy Kvôli efektívnejšej práci s akciou odporúčame do každej akcie doplniť nasledujúci riadok kódu: public static final String NAME = getunieuqname(#atribút#.class); Kde # ATRIBÚT # predstavuje názov triedy atribútu. Vďaka tomu je možné následne jednoducho získavať akciu z IAttribudeModel. Roloženie akcií a atribútov medzi projekty je zobrazené na obrázku Obrázok 7. Obrázok 7 - rozloženie akcí a atribútov 11
MESSAGE MODULE Naša architektúra používa distribuované riadenie agentov, to znamená, že každý agent sa správa, ako samostatná jednotka. Simulácia vyžaduje, aby agenti medzi sebou komunikovali a z tohto dôvodu vznikol modul sprav. Modul sprav tvorí komunikačný kanál, cez ktorý komunikujú agenti podobne, ako pri servisne orientovaných architektúrach komunikujú dva systémy asynchrónnymi správami. Požiadavky na prácu tohto modulu preto boli podobné, ako pre spomínané systémy. Príjemca správy nemusí byť prítomný, pri jej odosielaní a odosielateľ nemusí byt prítomný pri jej doručení. Jadro modulu správ Jadro modulu správ bolo navrhnuté počas prvých prototypov a doteraz sa jeho stavba z pohľadu návrhu nezmenila. Modul je reprezentovaný pod rozhraním, pretože v prípade zmeny celého modulu za iný netreba jeho časté používanie opravovať na iných miestach. Mailbox Táto trieda predstavuje úložisko správ poslaných konkrétnemu agentovi, ktorý je v simulácií evidovaný pod svojím ID. Správy sa ukladajú do schránky počas celého času a pri výbere sa odstraňujú zo zoznamu. PostMailbox Táto trieda predstavuje centrálne úložisko poštových schránok agentov. Poštová schránka ak neexistuje tak sa inicializuje na ID agenta, ktorému je správa určená. DefaultMessageModule Táto trieda predstavuje defaultnú implementáciu základného rozhrania. Táto trieda slúži na sprostredkúvanie činnosti modulu medzi jej pod vrstvami. class Message modul... «interface» messagemodule::imessagemodule + getmessages(long, long) : Collection<Message> + sendmessage(long, long, String) : Message + sendmessage(long, long, String, int) : Message DefaultMessageModule {leaf} + getmessages(long, long) : Collection<Message> - sendmessage(message, long) : void + sendmessage(long, long, String) : Message + sendmessage(long, long, String, int) : Message messagemodule::message - action: String - agentidfrom: long - agentidto: long - details: UniversalMap = new UniversalMap() - step: int = 0 + adddetail(string, Object) : Message + getaction() : String + getagentidfrom() : long + getagentidto() : long + getdetails() : UniversalMap + getstep() : int + newmessage(string, long, long, int) : Message + newmessage(string, long, long) : Message PostMailbox + postoffice: HashMap<Long, Mailbox> = new HashMap<Lon... + getmessages(long, long) : Collection<Message> + sentmessage(message, long) : void Mailbox + messages: Collection<Message> = new ArrayList<... + addmessage(message) : void + clean() : void + getallmessages(long) : Collection<Message> 12
Message Táto trieda predstavuje samotnú správu, ktorá je posielaná medzi agentmi. Táto trieda má vystavené fluent API, za pomoci ktorého sa jednoduchšie pracuje zo samotnou správou počas jej vytvárania. Fluent API Použitie tohto API je jednoduché pre používateľa a začína samotným rozhraním, ktoré pri posielaní správy vracia používateľovi už samotnú správu, pri takomto vytvorení správy je nutné zadať odosielateľa, príjemcu a kľúčové slovo. Do správy, môže užívateľ potom nezávisle pridávať ďalšie parametre tela správy, ktoré sa nijak neupravujú v samotnom modeli správ. Telo správy je tvorené mapou objektov, ktoré sú uložené pod kľúčmi zadanými užívateľom. Použitie v akciách Použitie odoslania správ v akciách je veľmi jednoduché, iba sa použije API modulu správ na odoslanie správ. Použitie prijatia správy je pre akciu iba raz a kľúčové slovo správy predstavuje slovný identifikátor samotnej akcie, pri prijatí správy sa dá pracovať zo samotným telom správy. Telo správy obsahuje to čo mu bolo zadané pri vytváraní a preto akcia predstavuje základné dve časti a to je odosielanie správy a prijatie správy, pretože agenti musia vedieť prijať správu od iného agenta, majú všetci agenti prístupné spracovanie správy, odosielanie nemusia mať. Správy ako pamäť agenta Samotná správa sa najčastejšie používa ako pamäť agenta ohľadom nejakej udalosti súvisiacej s riadením správania agenta, pretože spracovanie správy vykonáva agent vo svojej akcii spracovania správ je možné v tele udržovať veľké množstvo informácií a pri správnom použití to nezvyšuje pamäťové nároky. Spôsob použitia v tomto špecifickom prípade je vytvorenie objektu, ktorý je nositeľom údajov a vložením tohto objektu do správy pod zvoleným kľúčom. Objekt vložený do správy je možné vždy vybrať a predoslať znova bez vytvorenia novej inštancie. Použitie v cykle rozhodovania agenta Počas cyklu agenta sa správy vždy na začiatku tohto cyklu vyberú z MailBoxu a nechajú spracovať akciami, pri vyberaní správ za v požiadavke na výber nachádza ID agenta a krok v ktorom agent správu vyberá, pretože niektoré správy sú určené na vybratie v špecifickom kroku alebo v kroku za daným bodom. Problémy a návrhy na zlepšenie Problém s výberom správy v konkrétnom kroku. Každý agent vykonáva kroky, ale aj napriek tomu sa stáva, že agenti sa nachádzajú v rôznych krokoch a to aj z veľkým rozdielom, to spôsoby, že agent posielajúci správu nepozná číslo kroku agenta na doručenie. Zlepšenie by bolo previesť číslo kroku na číslo, ktoré predstavuje číslo krokov počas ktorých sa správa ešte vybrať nemôže. 13
Problém posielania správy. Pri použití terajšieho fluent API je správa zaradená do schránky už po jej vytvorení a preto, ak by sa v budúcnosti plánovalo použiť viac vláknové simulačné prostredie by takéto použitie mohlo spôsobiť, že agent primajúci správu ju zažína čítať skôr než agent odosielajúci správu doplní jej telo. Odstrániť tento problém by bolo možné za predpokladu, že by sa správa odosielala až po zavolaní funkcie odosielania po pridaní všetkých parametrov. 14
GEOMETRY MODULE PATHPLIESKANICA /HumanModelCore/src/sk/fiit/steam/geometry/PathPlieskanica.java Úlohou PathPlieskanice, je nájsť najkratšiu cestu medzi dvoma zadanými bodmi. Na to poskytuje 2 metódy: List<Coordinate> getshortestpath(point start, Point destination) List<Coordinate> getshortestpathclosestto(point start, Point destination) Rozdiel v týchto metódach je jediný, a to cesta, ktorú vrátia. Tento rozdiel môžeme vidieť na obrázkoch nižšie (Obrázok 8 a Obrázok 9). V metóde getshortestpath sa zadaný bod start a destination skutočne pridá do grafu a následne sa nájde cesta. Pri druhej metóde getshortestpathclosestto sa nájdu najbližšie body k zadaným bodom a z nich sa hľadá cesta. Z týchto menších rozdielov vyplíva, že pri častom hľadaní cesty veľkým počtom agentov, je výhodnejšie využiť metódu getshortestpathclosestto, pretože sa do grafu nepridá veľké množstvo nových bodov ako pri druhej metóde. Avšak táto metóda je pomalšia, pretože musí hľadať najbližšie body. Obrázok 8 - cesta nájdená pomocou metódy getshortestpath 15
PathPlieskanica sa využíva nasledovne: Obrázok 9 cesta nájdená pomocou metódy getshortestpathclosestto List<Coordinate> waypoints = PathPlieskanica.INSTANCE.getShortestPath(p1, p2); agent.setwaypoints(waypoints); pričom p1 a p2 sú ľubovolné body vytvorené napríklad pomocou factory triedy: Factory.createPoint(50.4, 20.8) Podmienkou fungovania PathPlieskanice je prítomnosť grafu v GraphPlieskanici. GRAPHPLIESKANICA /HumanModelCore/src/sk/fiit/steam/geometry/GraphPlieskanica.java Úlohou GraphPlieskanice je vytvorenie grafu, ktorý využíva PathPlieskanica. V súčasnosti sa graf vytvára na začiatku simulácie v metóde main triedy MainSteam, ale je možné ho vytvoriť kedykoľvek počas simulácie, avšak jeho vytváranie trvá niekoľko sekúnd (v závislosti od parametrov stroja). O priebehu vytvárania grafu informuje progressbar. Použitie: GraphPlieskanica.INSTANCE.createGraph(WaypointPlieskanica.getInstance().generateWaypo ints(1, 15, 15)); Hlavnou metódou GraphPlieskanice je teda vytvorenie grafu z daných bodov: SimpleWeightedGraph<Point, DefaultWeightedEdge> creategraph(collection<point> waypoints) Vytvorený graf je ohodnotený, takže hodnota hrany predstavuje reálnu vzdialenosť medzi dvoma bodmi, ktoré spája. Graf je uložený v premennej graph, ktorú využíva PathPlieskanica na nájdenie cesty. 16
GraphPlieskanica obsahuje jednu konštantu (MAX_EDGE_DISTANCE = 22.0), ktorá určuje hustotu grafu resp. najväčšiu povolenú dĺžku hrany. To znamená, že vyššie hodnoty spôsobia rapídny nárast počtu hrán v grafe a teda pomalejšie hľadanie najkratšej cesty. Nižšie hodnoty zrýchlia hľadanie cesty, pretože graf bude obsahovať menej hrán, avšak pri príliž nízkej hodnote môže dôjsť k neprepojeniu žiadaných bodov a teda nemožnosti nájdenia cesty medzi nimi. Z toho vyplíva, že túto hodnotu treba zvoliť opatrne v závislosti od bodov, z ktorých sa graf vytvára. Okrem toho poskytuje aj ďalšie metódy: addifdontexist(simpleweightedgraph<point, DefaultWeightedEdge> graph, Point start, Point destination) addpointtograph(point p, SimpleWeightedGraph<Point, DefaultWeightedEdge> graph) Point getclosestifdoesntexist(point point, Graph<Point, DefaultWeightedEdge> graph) Tieto metódy využíva PathPlieskanica pri nastavovaní bodov, z ktorých sa hľadá cesta. Z ich názvov je jasné čo robia: addifdontexist addpointtograph getclosestifdoesntexist do grafu pridá jeden aj druhý bod ak sa v grafe ešte nenachádzajú a spojí ich hranami so všetkými bodmi v MAX_EDGE_DISTANCE vzdialenosti do grafu pridá bod a spojí ho hranami so všetkými bodmi v MAX_EDGE_DISTANCE vzdialenosti nájde najbližší bod k danému bodu (ak je daný bod už prítomný v grafe alebo žiadny najbližší bod neexistuje, vráti daný bod) WAYPOINTPLIESKANICA /HumanModelSurface/src/sk/fiit/steam/geometry/WaypointPlieskanica.java Úlohou WaypointPlieskanice je vytvorenie bodov (waypointov), po ktorých sa môžu agenty pohybovať. Tieto body sú následne vložené do GraphPlieskanice, z ktorých sa vytvorí graf. Použitie: List<Point> waypoints = WaypointPlieskanica.getInstance().generateWaypoints(1, 15, 15) Ako už bolo spomínané v dokumentácii k inžinierskemu dielu, waypointy sú generované dvoma spôsobmi: 1. Vytvorenie statickej mriežky, ktorej priesečníky určujú waypointy 2. Waypointy sú poukladané popri prekážkach Hlavnou metódou tejto plieskanice je vytvorenie waypointov: List<Point> generatewaypoints(double distancefromobstacle, double pointdensity, double griddensity) Táto metóda zahŕňa v sebe oba spomínané spôsoby. Parametre metódy prispôsobujú výsledné rozloženie bodov: 17
distancefromobstacle pointdensity griddensity Vzdialenosť medzi prekážkami a bodmi, ktoré sú vytvárané pomocou druhého spôsobu 0 = body ležia na prekážke 1 a viac = body sú vzdialené od prekážky Vzdialenosť medzi samotnými bodmi, ktoré sú generované okolo prekážok (tiež druhý spôsob) táto vzdialenosť sa vzťahuje len na body na rovnej čiare, t.j. nech je hodnota akákoľvek, vždy bude bod prítomný na rohu prekážky (tam kde sa stretávajú 2 steny prekážky) 0 alebo veľké číslo = len body pri rohoch prekážky 1 a viac = vzdialenosť medzi bodmi (viď obrázky nižšie) Vzdialenosť medzi bodmi na mriežke (prvý spôsob) Obrázok 10 Vplyv parametra pointdensity na vygenerované body (0 vľavo, 5 vpravo) Okrem hlavnej metódy na vytvorenie waypointov sa tu ešte nachádzajú: List<Point> reducepoints(list<point> list, double distance) { Point getrandompoint() Metóda ReducePoints sa pokúsi zredukovať počet waypointov v danej vzdialenosti, tj. ak sú dva body od seba vzdialené o distance tak jeden z nich sa vymaže. Táto metóda má však svoje chyby, pretože môže zrušiť dôležité body na rohu prekážky a tak úplne znemožniť nájdenie cesty okolo nej. Používať opatrne. Metóda getrandompoint vráti náhodný bod na mape, ktorý sa nachádza na ceste (t.j. nie v/na prekážke) WaypointPlieskanica obsahuje 3 premenné: private Simulation sim; private STRtree treepoints; private static final double SIMPLIFY_DISTANCE_TOLERANCE = 1.0; sim používa sa pri hľadaní náhodného bodu, a to na ohraničenie hľadanej oblasti (šírka a výška) treepoints špeciálna dátová štruktúra, v ktorej sú uložené vygenerované waypointy. Používa ju ObstaclePlieskanica na hľadanie najbližších bodov. Využitie STRtree má značný vplyv na performance, pretože umožňuje veľmi rýchle vyhľadávanie. SIMPLIFY_ Táto hodnota sa používa na zjednodušenie prekážok (pomocou metódy simplify 18
DISTANCE_ TOLERANCE z triedy TopologyPreservingSimplifier knižnice JTS) vyhladí nerovnosti na stenách prekážok v danej tolerancii OBSTACLEPLIESKANICA /HumanModelSurface/src/sk/fiit/steam/geometry/ObstaclePlieskanica.java ObstaclePlieskanica sa stará o všetko ohľadom prekážok. T.j. aj pri pohybe policajnej línie vypočítava krajné pozície línie, podľa najbližších prekážok a pod. Obsahuje tieto metódy: initialize(isimulation sim); List<Polygon> getobstacleswithoutholes(); List<Point> getclosestpoints(point p1, Collection<Point> list, double distance); Point getclosestpoint(point point, Collection<Point> list, double distance); LineString getlinetouchingobstacles(point point) initialize Metóda, ktorú je potrebné volať na začiatku simulácie naplní premenné prekážkami vytiahnutými zo súborov getobstacleswithoutholes Vráti zoznam prekážok typu Polygon z JTS knižnice, pričom prekážky sú tvorené len ich obrysom (exterior ring), t.j. neobsahujú diery. getclosestpoints Nájde všetky body, ktoré majú menšiu ako danú vzdialenosť voči danému bodu v danej kolekcii bodov getclosestpoint To isté ako predošlá metóda, avšak vráti len jeden najbližší bod getlinetouchingobstacles Vytvorí úsečku, ktorej krajné body sa dotýkajú najbližších prekážok a prechádzajú cez daný bod. Použité pri hľadaní úsečky na ktorej bude stáť policajná línia. Okrem týchto metód obsahuje aj metódy, ktoré nesúvisia s prekážkami. V budúcnosti by bolo vhodné ich vytiahnuť do Util triedy. Long getclosestneighbor(iagent agent, Enum grouptype, double maxdistance) isneighbourfromgroup(iagent agent, Enum grouptype, double distance) List<Long> getneighboursids(iagent agent, Enum grouptype, double distance) List<Long> getneighboursids(iagent agent, double distance) List<Point> getpointsonline(linestring line, double density) getclosestneighbor Vráti ID najbližšieho agenta, ktorý má daný typ a nachádza sa v danej vzdialenosti od daného agenta (vráti null ak nikoho nenájde) isneighbourfromgroup Zistí, či existuje nejaký agent daného typu v danom okruhu od daného agenta getneighboursids(3) Vráti ID-čka všetkých agentov, ktorý sú daného typu v danej vzdialenosti od daného agenta getneighboursids(2) Vráti ID-čka všetkých agentov v danej vzdialenosti od daného agenta getpointsonline Rozseká danú úsečku na body, ktoré sú od seba vzdialené o density POZOR! Metódy na zisťovanie susedov sú pomalé, t.j. ak sa volajú raz za niekoľko stepov (prípadne aj každý step) neovplyvní to simuláciu. Avšak keby každý agent v simulácii volal tieto metódy každý step (napríklad 500x každý step), simulácia bude sekať. Metódy boli vytvorené, kvôli nedeterministickému správaniu metód na hľadanie najbližších susedov v knižnici RVO2. 19
ObstaclePlieskanica obsahuje 4 premenné: private List<Polygon> obstacleswithoutholes; private Simulation sim; private final STRtree treeobstaclesnice = new STRtree(); private final STRtree treeobstacles = new STRtree(); Simulácia demonštrácie v meste sim Používa sa pri načítavaní prekážok obstacleswithoutholes Zoznam všetkých prekážok (len obvody, bez dier) treeobstaclesnice Špeciálna dátová štruktúra, v ktorej sú uložené vyhladené prekážky kvôli rýchlejšiemu vyhľadávaniu treeobstacles To isté ako predošlá premenná avšak bez vyhladených prekážok 20
DRAWING MODULE V tejto kapitole je bližšie opísaný modul, ktorého hlavnou úlohou je kresliť. V projekte Core existuje jednoduché rozhranie (abstraktná trieda), ktoré je následne implementované v projekte Surface. Existuje len jedna inštancia tohto rozhrania na čo treba pri ďalšom vývoji brať ohľad. DRAW API /HumanModelSurface/src/sk/fiit/steam/drawing/Draw.java API sa používa na dodatočné kreslenie do simulácie. V skutočnosti nekreslí priamo do okna simulácie, ale len vkladá kresby do štruktúry, ktorú vykresľuje MASON (tak ako vykresľuje agentov, prekážky, pozadie atď.). Štruktúra GeomVectorField drawings, ktorá uchováva kresby je uložená v triede Simulation, tak ako ostatné štruktúry, ktoré sa vykresľujú (obstacles, pois, agents, vehicles..). Aby bolo možné pristupovať k tejto štruktúre je potrebné nastaviť simuláciu do premennej v triede Draw. Toto sa vykonáva v konštruktore triedy Simulation (Draw.getInstance().setSimulation (this);). O samotné vykresľovanie sa starajú špeciálne triedy tzv. portrayaly (viď MASON dokumentáciu), pričom o kresby kreslené cez toto API sa stará trieda DrawingFieldPortrayal, do ktorej sa vloží už spomínaná štruktúra. Toto sa deje v triede SimulationWithUI (drawingportrayal.setfield( sim.drawings);) Použitie: Draw.getInstance().draw(DRAWING); AbstractDraw.getInstance().draw(DRAWING); - v Surface module - v Middle resp. Core module Pričom DRAWING môže byť: geometria knižnice JTS (bod, priamka, polygón,...) graf knižnice jgraph textový reťazec (String) obrázok (ImageIcon) Návratová hodnota metódy draw() je UUID. Je to jedinečné ID priradené nakreslenej kresbe. Kresbu je možné vymazať dvoma spôsobmi: erase(uuid id) - vymaže kresbu podľa daného ID erasealldrawings() - vymaže všetky doposiaľ nakreslené kresby cez toto API Samozrejme je možné zmeniť farbu, vyplnenie a veľkosť kresby. Na to slúžia metódy: setsettings(settings settings). setsettings(color color, boolean filled, double scale) Jednu z týchto metód je potrebné volať hneď pred metódou draw(). Zavolanie metódy spôsobí zmenu nastavení všetkých nasledujúcich kresieb. Parametre metódy sú: farba vyplnenie 21
veľkosť Taktiež je možné zmeniť farbu už nakreslených kresieb, a to pomocou metódy: repaint(uuid drawingid, Color color) Okrem spomínaných metód sa tu nachádzajú ešte 2 špeciálne metódy, ktoré sa využívajú na nakreslenie mŕtvych agentov (napríklad v metóde kill() triedy Agent): drawpolicecorpse(double x, double y) drawdemonstrantcorpse(double x, double y) Tieto metódy nakreslia náhodne vybranú textúru mŕtvoly na dané pozície x y. 22
ZVYŠNÉ MODULY IACCESSMAP Úlohou rozhrania IAccessMap je získavať informácie o agentoch a ich polohe. Metódy, ktoré toto rozhranie predpisuje sú nasledovné: IAgent getagent(long agentid) HashMap<Long, IAgent> getagenthashmap() List<Long> getagentneighborsid(long agentid, double distance) Viac o týchto metódách je napísane v javadocu. Toto rozhranie je možné zlepšiť o doplnenie metód, v ktorých by argumenty neboli ID agentov, ale referencie tejto triedy. Napríklad metóda: List<IAgent> getagentneighborsid(iagent agent, double distance) IRANDOMGENERATOR Vzhľadom na to, že existujú rôzne spôsoby ako generovať náhodné čísla, vytvorili sme rozhranie, ktorého referencia sa nachádza v triede ModuleMap. Vďaka tomu je možné v surface definovať generátor náhodných čísel, ktorý ponúka Mason a využiť ho pri písaní akcií. 23