Doc improvements

README.md

@@ -8,6 +8,15 @@
 Multiple programs for Minecraft [save file data extraction](#data-extraction-utilities) and [3D model generation](#3d-model-generation) based on save files.
 Also several well documented custom C libraries with minimal prerequisites for wavefront 3d model handling and Minecraft save file handling.
 
+[**User Manual**](https://tca166.github.io/mcSavefileParsers/md_doc_src_userManual.html)
+
+## Capabilities
+
+- Generate a 3d model based on your Minecraft savefile blazing fast
+- extract chunk nbt from region files
+- generate mtl from minecraft resource packs
+- generate obj files from minecraft resource packs
+
 ## Getting started
 
 In order to get started either download the parts of the precompiled release that apply to your system or compile the source code yourself.
@@ -148,7 +157,7 @@ These are compiled automatically using make, and then linked together into cNBT.
 Most of the code has been organized into four "libraries".
 These may prove to be useful should you want to parse Minecraft save files or generate wavefront 3D models.
 Feel free to use these as libraries in your projects just make sure to read the license before you do so.
-The documentation for functions in these libraries should be mainly in header files and on GitHub Pages, and I will gladly expand it should there be a need so just let me know.
+The documentation for functions in these libraries should be mainly in header files and on [GitHub Pages](https://tca166.github.io/mcSavefileParsers/), and I will gladly expand it should there be a need so just let me know.
 
 - regionParser  
     This library provides three functions for parsing region files.

doc/Doxyfile.conf

@@ -864,7 +864,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ./src ./README.md ./doc/src
+INPUT                  = ./src ./doc/index.md ./doc/src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1061,7 +1061,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ./README.md
+USE_MDFILE_AS_MAINPAGE = ./doc/index.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

doc/index.md

@@ -0,0 +1,8 @@
+# mcSavefileParsers
+
+[![CodeQL](https://github.com/TCA166/mcSavefileParsers/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/TCA166/mcSavefileParsers/actions/workflows/github-code-scanning/codeql)
+[![Linux](https://github.com/TCA166/mcSavefileParsers/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/TCA166/mcSavefileParsers/actions/workflows/c-cpp.yml)
+[![Windows](https://github.com/TCA166/mcSavefileParsers/actions/workflows/c-cppWin.yml/badge.svg)](https://github.com/TCA166/mcSavefileParsers/actions/workflows/c-cppWin.yml)
+
+Welcome to mcSavefileParsers documentation!
+This is generally intended to be a resource for developers, but here's a [**User Manual**](https://tca166.github.io/mcSavefileParsers/md_doc_src_userManual.html) for the layman on how to use the utilities.

doc/src/userManual.md

@@ -69,10 +69,11 @@ I created two handy Python scripts for generating these files, but you don't nee
 I have included one for your convenience in the repo.
 You will need to install Python to run them, but they shouldn't require any non standard libraries.
 When you install Python be sure to check the box that adds it to PATH.
-Having installed Python, get the absolute path of **the .minecraft directory** and run the following command in the repository directory:
+Having installed Python, you will need to find a Minecraft resource pack.
+Get the absolute path of **the /assets/minecraft** and run the following command in the repository directory:
 
 ```cmd
-python src/scripts/objGen.py *the .minecraft directory path*/assets/minecraft
+python src/scripts/objGen.py *path to /assets/minecraft directory of a resource pack*
 ```
 
 This will generate a special obj file in the repository directory.

doc/src/utilities.md

@@ -0,0 +1,127 @@
+# Utilities
+
+Quick overview of the developed utilities
+
+## Getting started
+
+In order to get started either download the parts of the precompiled release that apply to your system or compile the source code yourself.
+In order to compile use make, which is configured to allow for separate compilation of each utility, or complete compilation using the 'all' target ('windows' for cross-compilation).
+
+## Data extraction utilities
+
+Multiple utilities for Minecraft region file parsing.
+Either extract all [chunk NBT](https://minecraft.fandom.com/wiki/Chunk_format)s in a [region file](https://minecraft.fandom.com/wiki/Region_file_format) or just a single one.
+
+### regionFileReader
+
+This program extracts all the chunks in the given region file into nbt files that will be created in the provided directory.
+
+```Bash
+regionFileReader <path to region file> <output directory>
+```
+
+### chunkExtractor
+
+This program extracts only a single chunk with the given chunk coordinates into an nbt file.
+
+```Bash
+chunkExtractor <path to region directory> <x> <z>
+```
+
+## 3D model generation
+
+Multiple tools that can take in Minecraft related files as input and create 3D representations of your worlds
+
+### modelGenerator
+
+An open customizable chunk to 3d model converter.
+Takes in a chunk nbt file, a material file defining the look of blocks, an object file for non cube blocks and creates a 3d model based on that.
+Ideally the nbt file will be extracted using one of the tools above.
+
+```Bash
+modelGenerator <path to nbt file> ...
+```
+
+The program accepts the following additional arguments:
+
+- -l $y+ $y- :limits the result model to the given vertical range
+- -f :disables face culling
+- -h :displays help
+- -s $s :changes the block side in the result side to the given s argument
+- -m $filename :sets the given filename as the source mtl file
+- -o $filename :sets the given filename as the source special objects file
+- -out $filename :sets the given filename as the output filename
+
+#### Mtl format
+
+The generator if provided with the -m flag followed by the mtl file filepath will use the provided file as a material source and generate the obj file to support mtl materials. Blocks of minecraft:dirt will use a mtl material called dirt and so on. Feel free to create your own mtl file or use the mtl Gen to create one quickly.
+
+#### Obj format
+
+So in order to handle non cube blocks the generator needs an obj file defining models for those "special" blocks.
+If that file isn't provided the generator will simply assume everything is a cube.
+In order for the special obj file to get interpreted properly the vertex coordinates in each object must be relative to the center of the object.
+
+### radiusGenerator
+
+A version of modelGenerator using multiprocessing that can generate models same as modelGenerator, but with multiple chunks at the same time.
+This is the program you are going to want to use to generate your model.
+You provide coordinates of a chunk that will act as a center for your model, a radius in which surrounding chunks will be added to the model and the radiusGenerator will create a large model for you.
+The argument interface is very similar to modelGenerator and all rules about assets and limitations from modelGenerator apply here.
+That being said here is how you use radiusGenerator:
+
+```Bash
+radiusGenerator <path to region directory> <x> <z> <radius> ...
+```
+
+#### Cygwin
+
+You may want to compile the Linux version of radiusGenerator and use it under Windows for speed.
+You may accomplish that by installing [Cygwin](https://www.cygwin.com/) and compiling radiusGenerator in their environment.
+However due to POSIX shared memory management differing too greatly from Windows the cygserver needs to be running.
+In order to do that install the correct package, then run:
+
+```Bash
+cygserver-config
+net start cygserver
+```
+
+## Asset extractors
+
+Minecraft stores it's assets in it's own unique way.
+Due to this, and a need to provide assets for 3D model generators scripts were created.
+Naturally those assets aren't provided here since I want these programs to be Minecraft version independent (and I don't want to be sued).
+
+### mtlGen
+
+A script for generating complete and valid mtl files for modelGenerator
+
+```Bash
+mtlGen.py <path to /assets/minecraft/textures/block directory of a resource pack> ...
+```
+
+The script accepts the following additional arguments:
+
+- -s :Generates a simplified mtl file that doesn't use textures, but solid colors generated by averaging out RGBA values of all pixels
+- -t :Causes all textures with _top in name to be generated without it
+- -c :Enables green color correction to correct for the fact most vegetation textures are stored in greyscale
+
+Distribute the result at your own risk.
+
+### objGen
+
+A script for generating a complete obj file containing special object definition for modelGenerator
+
+```Bash
+objGen.py <path to /assets/minecraft directory of a resource pack>
+```
+
+Distribute the result at your own risk.
+
+### quickGen
+
+Batch script combining objGen.py and mtlGen.py in case you don't want to figure out how to use the two scripts
+
+```Bash
+./quickGen.sh <path to /assets/minecraft directory of a resource pack>
+```