DEVTOOLS: BladeRunner readme update

Also fixed broken modes for fontCreator and quotesSpreadsheetCreator scripts

4 files changed, 51 insertions, 19 deletions

diff --git a/devtools/create_bladerunner/subtitles/README.md b/devtools/create_bladerunner/subtitles/README.md
index 10d504f0eb..c11a021bb1 100644
--- a/devtools/create_bladerunner/subtitles/README.md
+++ b/devtools/create_bladerunner/subtitles/README.md
@@ -12,13 +12,19 @@ Note 1: A lot of extra information has been added to the output Excel file maint
 __The online Excel file is available here:__
 https://docs.google.com/spreadsheets/d/17ew0YyhSwqcqZg6bXrIgz0GkA62dhgViHN15lOu5Hj8/edit?usp=sharing
 
-Note 2: Using the "-xwav" switch, this tool will export __ALL__ game's audio files (that are either speech or speech-related) in a WAV format. This is expected to take up quite a lot of your HDD space.
+Syntax Notes: 
+1. The "-op" switch should be followed by the path to the folder where the WAV files should be exported; This folder path will also be used as input when the output Excel will be created (for the "INGQUO_E.TRE" sheet with the in-game quotes).
+2. The "-ip" switch should be followed by the path to the game's folder, where the TLK and MIX files reside.
+3. Using the "-xwav" switch, this tool will export __ALL__ game's audio files (AUD) (that are either speech or speech-related) in a WAV format. This is expected to take up quite a lot of your HDD space.
+4. Using the "-xtre" switch, the tool will add a sheet to the output Excel with the contents of each of the game's Text Resource files (TRE).
+5. You may use both, either or neither of the "-xwav" and "-xtre" switches, depending on what you need to do.
+6. The "--trace" switch enables extra debug messages to be printed. 
 
 Usage:
 ```
 python2.7 quoteSpreadsheetCreator.py -op folderpath_for_extracted_wav_Files [-ip folderpath_for_TLK_Files] [-ian pathToActorNamesTxt] [-m stringPathToReplaceFolderpathInExcelLinks] [-xwav] [-xtre] [--trace]
 ```
-The tool __requires__ the actornames.txt file, which is included in the samples folder.
+The tool __requires__ a valid path to the actornames.txt file; this file is included in the samples folder.
 
 
 ## mixResourceCreator (mixResourceCreator.py)
@@ -28,7 +34,22 @@ Usage:
 ```
 python2.7 mixResourceCreator.py -x excelWithTranscriptSheets.xls [-ian ./common/actornames.txt] [-cft pathToConfigureFontsTranslationTxt] [--trace]
 ```
-The tool __requires__ the actornames.txt file, which is included in the samples folder.
+The tool __requires__ a valid path to the actornames.txt file, which is included in the samples folder.
+
+Syntax Notes: 
+1. The "-x" switch is followed by the path to the input Excel file (xls) which should contain the transcript sheet(s).
+2. The "-ian" switch is followed by the path to the actornames.txt file -- if this is omitted then the actornames.txt is assumed to reside in the current working directory.
+3. The "-cft" switch is followed by the path to the text configuration file "configureFontsTranslation.txt" -- if this is omitted then the file is assumed to reside in the current working directory.
+4. The "--trace" switch enables extra debug messages to be printed. 
+
+The text configuration file "configureFontsTranslation.txt" a __text file that should be saved in a UTF-8 encoding (no BOM)__, that contains the following:
+1. A key "targetEncoding" with a value of the name of the ASCII codepage that should be used for the character fonts (eg windows-1253).
+2. Multiple lines with the key "fontNameAndOutOfOrderGlyphs" and a value that contains:
+    * the name of a in-game Font file that should be included in the SUBTITLES.MIX
+    * a '#' character after the font name
+	* a list of comma separated tuples that specify the mapping of special (out of order) character (see fontCreator) to placeholder characters from the selected codepage.
+	* eg. fontNameAndOutOfOrderGlyphs=SUBTLS_E#í:Ά,ñ:¥,â:¦,é:§,Ά:£
+
 
 ## fontCreator (fontCreator.py)
 (requires python Image library *PIL*)
@@ -64,7 +85,6 @@ The overrideEncoding.txt is a __text file that should be saved in a UTF-8 encodi
     * Example: specialOutOfOrderGlyphsUTF8ToAsciiTargetEncoding=í:Ά,ñ:¥,â:¦,é:§,Ά:£
     * Don't use space(s) between the tuples!
 There is a sample of such file in the source folder for the fontCreator tool.
-
 	
 __For the exporting the game fonts (to PNG) mode__, the valid syntax expects only one (1) argument:
 1. folderpathForMIXFiles: is the path where the game's MIX files are located (STARTUP.MIX is required). The exported font files will be: 10PT.FON.PNG, TAHOMA18.FON.PNG, TAHOMA24.FON.PNG and KIA6PT.FON.PNG.
@@ -84,6 +104,8 @@ It is highly recommended, though, that the input image file should contain only
 5. kerningForFirstDummyFontGlyph: This is an integer that explicitly indicates the kerning, ie. offset in pixels (on the x-axis) of the first glyph (the one that is repeated twice). This can be measured by observing the indent that your image processing app adds when you enter the first glyph (typically it should be only a few pixels)
 6. whiteSpaceWidthInPixels: This is a positive integer value that sets the width in pixels for the single white space between words for the subtitles in-game.
 
+The "--trace" switch enables extra debug messages to be printed. 
+
 A suggested method of creating decent looking PNG with the row of glyphs for your subtitles' font is the following:
 1. Create the font row in __GIMP__ 
     * Start with a __new__ empty image, with transparent background. Choose a large enough canvas width (you can adjust it later)     
diff --git a/devtools/create_bladerunner/subtitles/fontCreator/grabberFromPNG17BR.py b/devtools/create_bladerunner/subtitles/fontCreator/grabberFromPNG17BR.py
index c7ad8dc963..e0e48eef2b 100644
--- a/devtools/create_bladerunner/subtitles/fontCreator/grabberFromPNG17BR.py
+++ b/devtools/create_bladerunner/subtitles/fontCreator/grabberFromPNG17BR.py
@@ -45,7 +45,7 @@
 #           This should get rid of semi-transparent pixels while maintaining the "aliasing" effect. There could be a better way but this should work ok.
 
 
-# TODO: A way to export game fonts to png image (in order to be able to create new expanded fonts keeping glyph consistency!)
+# DONE: A way to export game fonts to png image (in order to be able to create new expanded fonts keeping glyph consistency!)
 #           Also override the corruption in TAHOMA18 while exporting
 # TODO: Re-Check the order of fonts in (in-game resource font files) TAHOMA18 (stored corrupted) and TAHOMA24 (in good condition).
 # TODO: print a warning for mismatch of number of letters in encoding override (or internal) and detected fonts in ROW IMAGE (especially if we expect a double exclamation mark at the start - and we ignoring one of the two)
@@ -1186,7 +1186,7 @@ def main(argsCL):
 
 	if invalidSyntax == True:
 		print "Invalid syntax\n Try: \n %s --help for more info \n %s --version for version info " % (app_wrapper_name, app_wrapper_name)
-		print "Valid syntax A - export game fonts:"
+		print "Valid syntax A - export game fonts to PNG images:"
 		print "%s -ip folderpath_for_MIX_Files [--trace]\n" % (app_wrapper_name)
 		print "Valid syntax B - create subtitle font:"
 		print "%s -im image_Row_PNG_Filename -om output_FON_filename -pxLL minSpaceBetweenLettersInRowLeftToLeft -pxTT minSpaceBetweenLettersInColumnTopToTop -pxKn kerningForFirstDummyFontLetter -pxWS whiteSpaceWidthInPixels [--noSpecialGlyphs] [--noAutoTabCalculation] [--trace]\n" % (app_wrapper_name)    # deductKerningPixels"
diff --git a/devtools/create_bladerunner/subtitles/mixResourceCreator/packBladeRunnerMIXFromPCTLKXLS04.py b/devtools/create_bladerunner/subtitles/mixResourceCreator/packBladeRunnerMIXFromPCTLKXLS04.py
index bf62889bb1..37d92ceb6e 100644
--- a/devtools/create_bladerunner/subtitles/mixResourceCreator/packBladeRunnerMIXFromPCTLKXLS04.py
+++ b/devtools/create_bladerunner/subtitles/mixResourceCreator/packBladeRunnerMIXFromPCTLKXLS04.py
@@ -15,6 +15,7 @@ ctypesLibFound = False
 csvLibFound = False
 xlrdLibFound = False
 reLibFound = False
+structLibFound = False
 
 try:
 	import shutil 
@@ -51,7 +52,14 @@ except ImportError:
 else:
 	reLibFound = True	
 
-if 	(not shutilLibFound) or (not ctypesLibFound) or (not csvLibFound) or (not xlrdLibFound) or (not reLibFound):
+try:
+	import struct 
+except ImportError:
+	print "Error:: struct python library is required to be installed!" 
+else:
+	structLibFound = True	
+	
+if 	(not shutilLibFound) or (not ctypesLibFound) or (not csvLibFound) or (not xlrdLibFound) or (not reLibFound) or (not structLibFound):
 	sys.stdout.write("Error:: Errors were found when trying to import required python libraries\n")
 	sys.exit(1)
 
@@ -64,6 +72,7 @@ from struct import *
 company_email = "classic.adventures.in.greek@gmail.com"
 app_version = "0.70"
 app_name = "packBladeRunnerMIXFromPCTLKXLS"
+app_wrapper_name = "mixResourceCreator.py"
 app_name_spaced = "Blade Runner MIX Resource Creator"
 app_short_desc = "Get a TRE file from spoken in-game quotes"
 numOfSpokenQuotes = 0
@@ -735,9 +744,9 @@ def main(argsCL):
 			print "Preparatory steps:"
 			print "1. Copy the BladeRunnerPCTLK.xls file (latest version, downloaded from Google Sheets) in some folder on your PC."
 			print "--------------------"
-			print "%s takes 1 mandatory argument:" % (app_name_spaced)
+			print "%s takes 1 mandatory argument:" % (app_wrapper_name)
 			print "Valid syntax: "
-			print "%s -x path_to_BladeRunnerPCTLK_xls [-ian path_to_actornames_txt] [-cft path_to_configureFontsTranslation_txt] [--trace]" % (app_name)
+			print "%s -x path_to_BladeRunnerPCTLK_xls [-ian path_to_actornames_txt] [-cft path_to_configureFontsTranslation_txt] [--trace]" % (app_wrapper_name)
 			print "-x is followed by the path to the excel file with the subtitle quotes."
 			print "-ian is followed by the path to actornames.txt, if it's not in the current working directory."
 			print "-cft is followed by the path to configureFontsTranslation.txt, if it's not in the current working directory."
@@ -787,9 +796,9 @@ def main(argsCL):
 		invalidSyntax = True
 
 	if invalidSyntax == True:
-		print "Invalid syntax\n Try: \n %s --help for more info \n %s --version for version info " % (app_name, app_name)
+		print "Invalid syntax\n Try: \n %s --help for more info \n %s --version for version info " % (app_wrapper_name, app_wrapper_name)
 		print "Valid syntax: "
-		print "%s -x path_to_BladeRunnerPCTLK_xls [-ian path_to_actornames_txt] [-cft path_to_configureFontsTranslation_txt] [--trace]" % (app_name)
+		print "%s -x path_to_BladeRunnerPCTLK_xls [-ian path_to_actornames_txt] [-cft path_to_configureFontsTranslation_txt] [--trace]" % (app_wrapper_name)
 		print "-x is followed by the path to the excel file with the subtitle quotes."
 		print "-ian is followed by the path to actornames.txt, if it's not in the current working directory."
 		print "-cft is followed by the path to configureFontsTranslation.txt, if it's not in the current working directory."
@@ -812,5 +821,5 @@ if __name__ == "__main__":
 	main(sys.argv[0:])
 else:
 	## debug
-	#print 'Debug:: %s was imported from another module' % (app_name)
+	#print 'Debug:: %s was imported from another module' % (app_wrapper_name)
 	pass
diff --git a/devtools/create_bladerunner/subtitles/quotesSpreadsheetCreator/sortBladeRunnerWavs02.py b/devtools/create_bladerunner/subtitles/quotesSpreadsheetCreator/sortBladeRunnerWavs02.py
index e85129c05e..ad29e7d2f8 100644
--- a/devtools/create_bladerunner/subtitles/quotesSpreadsheetCreator/sortBladeRunnerWavs02.py
+++ b/devtools/create_bladerunner/subtitles/quotesSpreadsheetCreator/sortBladeRunnerWavs02.py
@@ -37,7 +37,7 @@ except ImportError:
 else:
 	csvLibFound = True
 
-if 	(not shutilLibFound) or (not structLibFound) or (not csvLibFound):
+if 	(not shutilLibFound) or (not xlwtLibFound) or (not csvLibFound):
 	sys.stdout.write("Error:: Errors were found when trying to import required python libraries\n")
 	sys.exit(1)
 
@@ -53,6 +53,7 @@ from treFileLib import *
 company_email = "classic.adventures.in.greek@gmail.com"
 app_version = "0.70"
 app_name = "sortBladeRunnerWavs"
+app_wrapper_name = "quotesSpreadsheetCreator.py"
 app_name_spaced = "Blade Runner Transcript Excel Creator (bare bones)"
 app_short_desc = "Create an Excel (.XLS) for transcribing Blade Runner. It can also extract TRE files and export WAV files for game's resources. "
 traceModeEnabled = False
@@ -309,7 +310,7 @@ def inputMIXExtractTREs(inputMIXpath, excelOutBook = None):
 		break
 	for tmpMIXfileName in inputMIXFilesFound:
 		if traceModeEnabled:
-			print "Found MIX: %s" % ('"' + inputMIXpath + tmpMIXfileName + '"')
+			print "Found MIX: %s" % ('"' + tmpMIXfileName + '"')
 		errorFound = False
 		inMIXFile = None
 		#
@@ -562,8 +563,8 @@ def main(argsCL):
 			print "Created by Praetorian of the classic adventures in Greek team."
 			print "Always keep backups!"
 			print "--------------------"
-			print "%s takes has one mandatory argument, the folder of the extracted WAV files:" % (app_name)
-			print "Valid syntax: %s -op folderpath_for_extracted_wav_Files [-ip folderpath_for_TLK_Files] [-ian path_to_actornames_txt] [-m stringPathToReplaceFolderpathInExcelLinks] [-xwav] [-xtre] [--trace]" % (app_name)
+			print "%s takes has one mandatory argument, the folder of the extracted WAV files:" % (app_wrapper_name)
+			print "Valid syntax: %s -op folderpath_for_extracted_wav_Files [-ip folderpath_for_TLK_Files] [-ian path_to_actornames_txt] [-m stringPathToReplaceFolderpathInExcelLinks] [-xwav] [-xtre] [--trace]" % (app_wrapper_name)
 			print "The -op switch has an argument that is the path for extracted WAV files folder. The -op switch is REQUIRED always."
 			print "The -ip switch has an argument that is the path for the input (TLK or MIX) files folder (can be the same as the Blade Runner installation folder)."
 			print "The -ian switch is followed by the path to actornames.txt, if it's not in the current working directory."
@@ -757,8 +758,8 @@ def main(argsCL):
 		invalidSyntax = True
 
 	if invalidSyntax == True:
-		print "Invalid syntax\n Try: \n %s --help for more info \n %s --version for version info " % (app_name, app_name)
-		print "Valid syntax: %s -op folderpath_for_extracted_wav_Files [-ip folderpath_for_TLK_Files] [-ian path_to_actornames_txt] [-m stringPathToReplaceFolderpathInExcelLinks] [-xwav] [-xtre] [--trace]" % (app_name)
+		print "Invalid syntax\n Try: \n %s --help for more info \n %s --version for version info " % (app_wrapper_name, app_wrapper_name)
+		print "Valid syntax: %s -op folderpath_for_extracted_wav_Files [-ip folderpath_for_TLK_Files] [-ian path_to_actornames_txt] [-m stringPathToReplaceFolderpathInExcelLinks] [-xwav] [-xtre] [--trace]" % (app_wrapper_name)
 		tmpi = 0
 		for tmpArg in argsCL:
 			if tmpi==0: #skip first argument
@@ -780,5 +781,5 @@ if __name__ == '__main__':
 	main(sys.argv[0:])
 else:
 	## debug
-	#print 'Debug:: %s was imported from another module' % (app_name)
+	#print 'Debug:: %s was imported from another module' % (app_wrapper_name)
 	pass