path: root/README

           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                 FORNAX
             Collection of tools to visualize Path Finding
                               Algorithms

                                Andinus
           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Table of Contents
─────────────────

1. Demo
2. Installation
.. 1. Release
.. 2. From Source
..... 1. Without `git'
..... 2. With `git'
3. Documentation
.. 1. Options
4. Project Structure
5. Fornax Format
.. 1. Grids
6. News
.. 1. v0.1.0 - 2021-11-03


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Website          <https://andinus.unfla.me/projects/fornax>
 Source           <https://git.unfla.me/fornax>
 GitHub (mirror)  <https://github.com/andinus/fornax>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This collection includes:
• `fornax': Program that parses /Fornax Format/ and outputs video
  solution.
• Algorithms: Various algorithms solved in several programming
  languages.


1 Demo
══════

  Solution for /DFS-33/, generated on /2021-11-03/ (click to play).

  [https://andinus.unfla.me/resources/projects/fornax/2021-11-03-DFS-33.png]


[https://andinus.unfla.me/resources/projects/fornax/2021-11-03-DFS-33.png]
<https://andinus.unfla.me/resources/projects/fornax/2021-11-03-DFS-33.mp4>


2 Installation
══════════════

  `fornax' is written in Raku, it can be installed with `zef'. You can
  also run it without `zef', just run `raku -Ilib bin/fornax' from
  within the source directory.

  • *Note*: `Cairo' module & `ffmpeg' program is required.


2.1 Release
───────────

  1. Run `zef install fornax'.

  Fornax should be installed, try running `fornax --version' to confirm.

  • Solving programs / solutions are not included in the distribution,
    get them from this repository.


2.2 From Source
───────────────

  You can either download the release archive generated by cgit/GitHub
  or clone the project if you have `git' installed.


2.2.1 Without `git'
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  1. Download the release:
     • <https://git.unfla.me/andinus/fornax>
     • <https://github.com/andinus/fornax/releases>
  2. Extract the file.
  3. Run `zef install .' in source directory.


2.2.2 With `git'
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  All commits by /Andinus/ will be signed by this [PGP Key].

  ┌────
  │ # Clone the project.
  │ git clone https://git.tilde.institute/andinus/fornax
  │ cd fornax
  │
  │ # Install fornax.
  │ zef install .
  └────


[PGP Key]
<https://andinus.nand.sh/static/D9AE4AEEE1F1B3598E81D9DFB67D55D482A799FD.asc>


3 Documentation
═══════════════

  Fornax parses /Fornax format/, generates a `PNG' for each iteration
  which is later converted to a slideshow with `ffmpeg'.

  • Solved paths are highlighted if the iteration is preceded by `|'.
  • Illegal paths are highlighted if the iteration is preceded by `!'.

  • *Note*: If the number of iterations are greater than an 8 digit
    number then the slideshow might be incorrect.


3.1 Options
───────────

  • `input': This takes solved input file in the /Fornax/ format.
  • `frame-rate': Frame rate for the video.
  • `output': Output directory (for solution video/images).


4 Project Structure
═══════════════════

  • Algorithms are located in `algorithms/' directory, sub-directory
    needs to be created for programming languages which will hold the
    actual source.

  • Sample solutions can be found in `resources/solutions/' directory.

    • *Note*: Some solutions might output illegal moves (like walking
      over blocked path), this error is only in visualization, the
      solution is correct.

      This has been fixed in commit
      `8cef86f0eb8b46b0ed2d7c37fa216890300249f6'.


5 Fornax Format
═══════════════

  Fornax format is an intermediate output file generated after solving
  the maze. Algorithms must output the solution in this format.

  ┌────
  │ rows:<number of rows> cols:<number of columns>
  │
  │ ...iterations
  └────

  `...iterations' is to be replaced by the resulting grid in each
  iteration that is to be included in the final video. Since the number
  of rows and columns is known, the whole grid should be printed in a
  single line.

  • Every iteration should be separated by a newline.

  • If the iteration cells is not equal to `rows * columns' or `(rows *
      columns) + 1' then it may be ignored by the program that parses
      the file.

  • Solved iteration can be preceded by `|' character.

  • Iteration that tries to walk on a blocked path can be preceded by
    `!' character.

  • First iteration is assumed to be the maze.


5.1 Grids
─────────

  A grid is printed for every iteration. Grids are composed of cells.

  ━━━━━━━━━━━━━━━━━━━━━━━━━━
   Cell              Symbol
  ──────────────────────────
   Path              `.'
   Blocked           `#'
   Destination       `$'
  ──────────────────────────
   Visited           `-'
   Current Position  `@'
  ━━━━━━━━━━━━━━━━━━━━━━━━━━

  • /Current Position/ is prioritized over /Blocked/ & /Destination/
    symbol if it makes sense.


6 News
══════

6.1 v0.1.0 - 2021-11-03
───────────────────────

  ⁃ Initial implementation. Includes DFS solver in Java, tool to
    visualize the solution.