Projekt_Sztuczna_Inteligencja

Klasa JsonGenerator służy do generowania/edytowania/tworzenia, oraz zapisu/odczytu cech krat (map) z których generowane będą środowiska działania agenta. Cechy krat zapisywane są w formie struktury Json. Dzięki tej klasie można tworzyć pola o różnych kolorach, miny o różnych typach, zapisać startową pozycję agenta. Następnie możliwe jest zapisanie utworzonych danych w plikach, ich odczyt, a także pobranie danych w formie słownika.

Klasa JsonGenerator nie zwraca środowiska w którym agent może działać, a jedynie dane z których takie środowisko można utworzyć.

2 Ogólna zasada działania klasy JsonGenerator

Jedna instancja klasy JsonGenerator w każdym momencie może służyć tylko do edycji danych jednej kraty. Dane na temat kraty są przechowywane w polu grid, który jest słownikiem. Wywoływanie metod edytujących cechy kraty edytuje słownik grid. W wypadku zapisu danych do pliku plik Json jest generowany na podstawie stanu pola grid, a w wypadku wczytywania kraty dane są wczytywane do tego pola. Aktualny stan słownika grid można pobrać za pomocą metody get_grid().

Pole grid składa się ze słowników przechowywujących dane odpowiednich pól na planszy. Pola te identyfikowane są po numerze wiersza i kolumny w jakiej się znajdują. Przy czym implementacje metod zawartych w tej klasie zakładają, że numer wiersza oraz kolumny numeruje się od zera. Następnie te słowniki mogą w polu mine zawierać (nie muszą) podobne struktury logiczne przechowywujące informacje na temat min.

Wizualizacja numerowania danych w macierzy przyjęta w projekcie:

[0][0] [0][1] [0][2] [0][3] ...
[1][0] [1][1] [1][2] [1][3] ...
[2][0] [2][1] [2][2] [2][3] ...
... ... ... ...

Wizualizacja zapożyczona z dokumentacji Minefield (aut. Bartłomieja Grochowskiego)

3 Powiązane pliki

3.1 project_constants.py

Plik ten zawiera różnego rodzaju stałe wartości jak również szablony obiektów, na podstawie których klasa JsonGenerator generuje i zapisuje obiekty JSON. Wszystkie istotne dla działania klasy obiekty znajdują się w sekcji STRUCTS -> USED BY JSON GENERATOR tego pliku.

STRUCT_TILE_COLORS - tablica zawierająca nazwy kolorów kafelków, za pomocą której klasa JsonGenerator tworzy dane losowych plansz.

STRUCT_MINE_TYPES - tablica zawierająca nazwy typów min, za pomocą której klasa JsonGenerator tworzy dane losowych plansz.

HARDCODED_VALUES - tablica w której zdefiniowane są pola kluczy z wartościami na stałe przypisanymi minom, aby nie dało się ich zmienić przy zmianach specjalnych parametrów min.

STRUCT_MINE_ATTRIBUTES - słownik, zawierający podstawowe szablony min z wartościami domyślnymi. Używany do konstruowania obiektów JSON.

STRUCT_MINE_ATTRIBUTE_TYPES - słownik zawierający dane pomocnicze do generowania losowych plansz. Dane te to informacje na temat jaki typ specjalnych danych należy wygenerować dla poszczególnych min.

4 Struktura danych

4.1 Python

Legenda:

Ogólne:
grid - słownik w którym przechowywane są dane na temat kraty

Początkowy stan agenta:
position - "row,column"
direction - int (wartość z enum'a Direction, istniejącego w pliku project_constants.py)

Miny - wspólne:
row, column - pozycja kafelka
color - kolor kafelka
mine - mina która stoi na danym kafelku (nieobowiązkowo)
mine_type - typ miny na kafelku (o ile mina istnieje)

Miny - ChainedMine:
predecessor - poprzednik miny
p_row, p_column - pozycja poprzednika miny

Miny - TimeMine:
timer - pole zawierające czas do detonacji
time_until_detonation - czas do detonacji

grid["agents_initial_state"] = {
    "position": position,
    "direction": direction
}

grid["row,column"] = {
    "color": color,
  "mine": None
}

grid["row,column"] = {
    "color": color,
  "mine": {
    "mine_type": "standard"
  }
}

grid["row,column"] = {
    "color": color,
  "mine": {
    "mine_type": "chained",
    "predecessor": "p_row,p_column"
  }
}

grid["row,column"] = {
    "color": color,
  "mine": {
    "mine_type": "time",
    "timer": time_until_detonation
  }
}

4.2 Json

Legenda:

Początkowy stan agenta:
position - "row,column"
direction - int (wartość z enum'a Direction, istniejącego w pliku project_constants.py)

Miny - wspólne:
rowi, columni - pozycja i-tego kafelka
color - kolor kafelka
mine - mina która stoi na danym kafelku (nieobowiązkowo)
mine_type - typ miny na kafelku (o ile mina istnieje)

Miny - ChainedMine:
predecessor - poprzednik miny
p_row, p_column - pozycja poprzednika miny

Miny - TimeMine:
timer - pole zawierające czas do detonacji
time_until_detonation - czas do detonacji

{ // start of json
  "agents_initial_state": {
    "direction": direction,
    "position": position
  }
  
  "row1,column1": {
    "color": color1,
    "mine": null
  }
  
  "row2,column2": {
    "color": color2,
    "mine": {
      "asset": StandardMineAssetLetter,
        "mine_type": "standard"
        }
    } 
    
  "row3,column3": {
    "color": color3,
    "mine": {
      "asset": ChainedMineAssetLetter,
      "mine_type": "chained",
      "predecessor": "p_row,p_column"
    }
  }
  
  "row4,column4": {
    "color": color4,
    "mine": {
      "asset": TimeMineAssetLetter,
      "mine_type": "time",
      "timer": time_to_detonation
    }
  }
  
  ... // other tile instances
} // end of json

5.1 Metody oraz konstruktor

5.1.1 - konstruktor - JsonGenerator(agents_initial_position=(0, 0), agents_initial_direction=Direction.Up.value)

agents_initial_position - (row: int, column: int)
agents_initial_direction - int (wartość z enum'a Direction, istniejącego w pliku project_constants.py)

Do konstruktora można przekazać parametry, ustawiające pozycje startową agenta i jego kierunek zwrotu. Wartoście te można zmieniać za pomocą metody set_agents_initial_state(position, direction).

5.1.2 - set_agents_initial_state(position=(0, 0), direction=Direction.Up.value)

position - (row: int, column: int)
direction - int int (wartość z enum'a Direction, istniejącego w pliku project_constants.py)

Modyfikuje dane odpowiadające stanu początkowemu agenta. Ustawia pozycje początkową oraz początkowy kierunek zwrotu agenta. Dane te są zapisane i przy tworzeniu dowolnej kraty są wykorzystywane. (nie dotyczy wczytywania kraty z plików)

5.1.3 - generate_randomized_grid(dimensions, mine_appearance_chance=0.15, predecessor_chance_decrease=0.25)

dimensions - (num_of_rows: int, num_of_columns: int)
mine_appearance_chance - float (szansa wystąpienia dowolnej miny na polu wyrażona w miarze [0,1]*100%)

Tworzy kratę o podanych wymiarach z losowymi polami oraz minami. Szansa na wystąpienie miny na polu jest zależna od parametrów przekazywanych do funkcji. Usuwa poprzednio istniejącą kratę. Pozycja startowa agenta nie jest losowa, tylko brana z pola agent_starting_position.

5.1.4 - add_tile(position, color)

position - (row: int, column: int) | "row,column"
color - color: string

Tworzy wpis o polu bez miny o podanym kolorze na podanej pozycji. W razie istnienia wpisu pola na podanej pozycji, wcześniej istniejący wpis jest nadpisywany.

5.1.5 - add_tile_with_a_mine(position, color, mine_type, attribute_values=[])

position - (row: int, column: int) | "row,column"
color - color: string
minetype - mine_type: string (char)
attribute_values - [value: basic_type]

Tworzy wpis o polu z miną na podanej pozycji. Pole jest ma przypisany kolor color, oraz minę o typie mine_type. Jeśli mina jest specjalnego typu i posiada zdefiniowane pola inne niż te z abstrakcyjnej klasy Mine, to można je nadpisać przekazując listę wartości w miejsce argumentu attribute_values. W razie istnienia miny w podanym polu typ miny jest nadpisywany. W razie istnienia wpisu pola na podanej pozycji, wcześniej istniejący wpis jest nadpisywany.

Przykład dla tworzenia kafelka z miną typu ChainedMine:
add_a_tile_with_a_mine((row1,column1), "some_color", "chained", ["row2,column2"]), gdzie row2, column2, to pozycja następnika.

5.1.6 - delete_a_tile(position)

position - (row: int, column: int) | "row,column"

Usuwa wpis o polu z podanej pozycji.

5.1.7 - set_a_mine(position, mine_type, attribute_values)

position - (row: int, column: int) | "row,column"
mine_type - mine_type: string (char)
attribute_values - [value: basic_type]

Dodaje do wpisu pola na podanej pozycji minę typu mine_type. Jeśli mina jest specjalnego typu i posiada zdefiniowane pola inne niż te z abstrakcyjnej klasy Mine, to można je nadpisać przekazując listę wartości w miejsce argumentu attribute_values. W razie istnienia miny w podanym polu typ miny jest nadpisywany.

Przykład dla miny typu ChainedMine, która posiada jedno dodatkowe pole (predecessor):
add_a_mine((row1,column1), "chained", ["row2,column2"]), gdzie row2, column2, to pozycja następnika.

5.1.8 - delete_a_mine(position)

position - (row: int, column: int) | "row,column"

Usuwa z wpisu pola na podanej pozycji minę.

5.1.9 - get_tile(position)

position - (row: int, column: int) | "row,column"

Zwraca słownik z danymi na temat pola na pozycji position.

5.1.10 - get_mine(position)

position - (row: int, column: int) | "row,column"

Zwraca słownik z danymi na temat miny istniejącej na pozycji position, lub wartość None jeśli mina nie istnieje.

5.1.11 - get_grid()

Zwraca słownik zawierające dane na temat wszystkich pól zdefiniowanych w obecnym stanie instancji klasy. Innymi słowy zwraca pole grid.

5.1.12 - clear_grid()

Usuwa wszystkie wpisy ze słownika grid. Nie usuwa pozycji startowej agenta.

5.1.13 - load_from_a_file(file_path)

file_path - string (ścieżka do pliku)

Wczytuje do własnego słownika grid dane z jsona. Poprzednio składowana mapa przepada.

5.1.14 - save_to_a_file(file_path, access_mode)

file_path - string (ścieżka do pliku)
access_mode - ('w' - write) or ('a' - append)

Zapisuje obecny stan słownika grid do pliku za pomocą podanej metody dostępu ('w' - write, 'a' - append).

5.1.15 - edit_a_file(file_path)

file_path - string (ścieżka do pliku)

Działa jak metoda save_to_afile(file_path, access_mode) ale edytuje tylko te wpisy które zostały utworzone w obecnej wersji pola grid, jeśli pole(x,y) istnieje w pliku edytowanym, ale nie zostało na nowo zdefiniowane w tej instancji klasy to pozostanie ono w pliku edytowanym bez zmian.

5.2 Funkcje statyczne

5.2.1 - create_a_mine(mine_dict, position)

mine_dict - słownik zawierający informacje na temat miny. (można pozyskać za pomocą get_mine(position) [5.1.10])
position - (row: int, column: int) | "row,column"

Zwraca instancję klasy StandardMine, lub ChainedMine, lub TimeMine zależnie od danych przekazanych w słowniku. Ustawia parametry min, z wyjątkiem poprzednika miny łańcuchowej, jako że funkcja nie ma dostępu do poprzednika takiej miny.

5.2.2 - create_a_tile(tile_dict, position)

tile_dict - słownik zawierający informacje na temat pola. (można pozyskać za pomocą get_tile(position) [5.1.9])
position - (row: int, column: int) | "row,column"

Zwraca instancję klasy Tile z parametrami zależnymi od przekazanego słownika zawierającego informacje na temat tworzonego pola. W wypadku tworzenia pola z miną łańcuchową, nie przypisuje minie łańcuchowej poprzednika jako że nie ma dostępu do poprzednika takiej miny.

5.2.3 - get_chained_mine_and_its_predecessor_pairs(minefield_dictionary)

minefield_dictionary - słownik zawierający informacje na temat kraty. (składającej się z wielu pól)

Zwraca listę par - mina łańcuchowa i jej poprzednik - istniejących w przekazanym słowniku zawierającym informacje na temat pól i ich min.

Format zwracanych danych: [(chained_mine_position, its_predecessor_position), ...]
gdzie position - (row: int, column: int)

5.2.4 format_position_to_str(position)

position - (row: int, column: int) | "row,column"

Zwraca pozycje w formacie "row,column", lub wartość None, gdy wprowadzone zostały niepoprawne dane.

5.2.5 format_position_to_tuple(position)

position - (row: int, column: int) | "row,column"

Zwraca pozycje w formacie (row: int, column: int), lub wartość None, gdy wprowadzone zostały niepoprawne dane.

6 Przykładowe dane

6.1 krata [3*3]

Kod wykorzystany do wygenerowania kraty:

import json_generator as jg

json_generator = jg.JsonGenerator()
json_generator.generate_randomized_grid((3, 3), 0.5, 1)

{
  "0,0": {
    "color": "PURPLE",
    "mine": null
  },
  "0,1": {
    "color": "GREEN",
    "mine": null
  },
  "0,2": {
    "color": "RED",
    "mine": {
      "mine_type": "time",
      "timer": 8
    }
  },
  "1,0": {
    "color": "RED",
    "mine": {
      "mine_type": "chained",
      "predecessor": null
    }
  },
  "1,1": {
    "color": "GREEN",
    "mine": {
      "mine_type": "standard"
    }
  },
  "1,2": {
    "color": "PURPLE",
    "mine": null
  },
  "2,0": {
    "color": "RED",
    "mine": {
      "mine_type": "chained",
      "predecessor": "1,0"
    }
  },
  "2,1": {
    "color": "BLUE",
    "mine": null
  },
  "2,2": {
    "color": "GREEN",
    "mine": null
  },
  "agents_initial_state": {
    "direction": 0,
    "position": "0,0"
  }
}