-----------------------------------------------------------------------
        HySP-Map Program Package  by INOUE and INDA
-----------------------------------------------------------------------
#############################
#### What is a HySP-Map? ####
############################# 

HySP-Map is a program for mapping unstained brain sections using hyperspectral cameras.
It processes the transmittance of the hyperspectral information of the brain sections using the Hyperspectral Phasor method and performs colourisation on the unstained brain sections.
These programs are written in MATLAB and assumes the use of koex files obtained with the hyperspectral camera of NH series from EBA Japan.
Hyperspectral images obtained with other cameras may also work with appropriate adjustments. (See below for details).

##################################################
#### Requirements and preparations before use ####
################################################## 

To run HySP- Map, you'll need to have the following prerequisites.

1) MATLAB (2021a or later Recommended)
	HySP- Map relies on MATLAB for its functionality. To use this software package, you must have MATLAB installed on your system. 
	The operating test environment was R2020a -R2022b. Operation with versions earlier than R2020a is not guaranteed.

2) hyperspectral image(koex.file)
	HySP- Map assumes 1000 x 1000 x 125 hyperspectral images taken as koex.files.
	The koex.file is obtained by NH series hyperspectral camera (Eba Japan, Japan).
	These files should be saved as background images and sample images respectively. Background and sample images must be saved in the same folder.

	The files should also be saved with the following naming scheme.
	<<background images>>
	SpectImg(100f,9.9ms,1g)_0_1_x10_Vs2_HoleMax.koex
	SpectImg(100f,9.9ms,1g)_0_2_x10_Vs2_HoleMax.koex
	SpectImg(100f,9.9ms,1g)_0_3_x10_Vs2_HoleMax.koex

	<< sample images>>
	SpectImg(100f,9.9ms,1g)_1_x10_Vs2_HoleMax.koex
	SpectImg(100f,9.9ms,1g)_2_x10_Vs2_HoleMax.koex
	SpectImg(100f,9.9ms,1g)_3_x10_Vs2_HoleMax.koex
	...

	For background images, get an empty area on the glass slide.
	Dust and air bubbles have a significant impact on the final output image, so try to exclude them as much as possible.

	With appropriate adjustments, other file formats can also be used. 
	See "To use hyperspectral images that are NOT koex files" in Usage for information on how to make adjustments.

3) Adequate memory capacity and storage

	A RAM capacity of at least 16 GB is recommended; operation with less than 16 GB depends on the number of koex file sequences, etc.
	In our test environment, we have observed a maximum memory occupation of approximately 10 GB during operation.

	There are also approximately 500 MB per MATLAB Data file for the Gaussian templates output during the process.
	Each output image is 2.5 MB.
	The total space required depends on the number of templates specified and the number of output images, but care should be taken to maintain sufficient storage space.

#######################
#### Usage Process ####
#######################

First, specify the folder where this program package exists as MATLAB's working folder. 
Then, when you activate the function HySP-MAPS, analysis will start automatically. 
There are several inputs required for the operation of HySP-MAPS, so please refer to the following.

An example of input is below.

==================================================================================================================================================

	Focus_Gaussian= [67 96 106 109 149];
	Focus_Imwrite= 1:3;
	Folder_Data = 'D:\Mouse';
	Folder_save = 'D:\Mouse\Images';
	Folder_Program = D:\HySP_ProgramPack';
	save_name_atatch = 'Mouse_HySP_MAP';
    
	HySP_MAPS(Focus_Gaussian,Focus_Imwrite,Folder_Data,Folder_save,Folder_Program,save_name_atatch)
 ================================================================================================================================================

It will work automatically if you enter the appropriate values.
You can find sample code "A_sample_code_to_run"

HySP_MAPS must have the following values:

- Focus_Gaussian ... Number of section image used to create Gaussian template (double type array)
- Focus_Imwrite ... Image number to be analyzed (double type array)
- Folder_Data ... koex. File storage folder (char type)
- Folder_save ... Output image storage folder (char type)
- Folder_Program ... folder location of HySP-Map saved
- save_name_atatch ... Save name prefix tag (char type)

And, optionnaly you can change these variables.

- Sigma_Param...σ value for coloring process (double type). Recommended is 1.5
- Harmonics_Num...Harmonics value of feather method (double type). Recommended is 1 or 2
- HSC_Width... Pixels size of x direction of hyperspectral images (double type)
- HSC_Height... Pixels size of y direction of hyperspectral images (double type)
- HSC_Band...Number of spectral bands (double type)
- HSC_BandSequence... you need to define the Band Sequence by linspace() function.  (double type)
                       please input linspace(Loweer limit, Higher limit, Number of spectral bands)
                       e.g. linspace(380,1000,125), it means 125 spectral bands from 380 nm - 1000 nm

The output image will be saved as a png file. One image is approximately 2.5MB.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++  To use hyperspectral images that are NOT koex files. +++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The koex file is a very specific file format and requires conversion for MATLAB processing.
The following is the processing code for the conversion. 
These codes are included in the programme packages "DataLoad.m" and "DataLoad2.m".

SAMPLE CODE=============================================================================================
	HSC_Width = 1000;
	HSC_Height = 1000;
	HSC_Band = 125;

	fid = fopen(FileName, 'r');
	a = fread(fid, HSC_Width*HSC_Height*HSC_Band,'uint16');
	fclose(fid);

	% Stored in an array
	HSC_ImageData=zeros(HSC_Width,HSC_Height,HSC_Band);
	for k = 1:HSC_Band
	    for j = 1:HSC_Height
        	for i= 1:HSC_Width
            		HSC_ImageData(j,i,k) = a(i + HSC_Width * HSC_Band *(j-1)+ HSC_Width *(k-1) ,1);
	        end
	    end
	end
=========================================================================================================

As can be seen, the koex data file contains numerical data written in uint16 type.
At the time of reading, this data is a double type data array of 125000000 x 1.
For subsequent processing, this data is converted into a 1000 x 1000 x 125 double type array in MATLAB.

If hyperspectral images from different suppliers are used, adjustments are necessary:
adjust HSC_Width = number of pixels in the x-direction of the image, HSC_Height = number of pixels in the y-direction of the image, HSC_Band = number of spectral bands to the appropriate values.

A similar process can be implemented in Python using the numpy package as follows.

SAMPLE CODE==============================================================================================
	import numpy as np
	HSC_Width = 1000
	HSC_Height = 1000
	HSC_Band = 125
	HSC_Num=HSC_Width*HSC_Height
	# Open the binary file for reading
	with open('D:\Mouse\SpectImg(100f,9.9ms,1g)_0_3_x10_Vs2_HoleMax.koex', 'rb') as file:
	# Read the binary data as uint16
	a = np.fromfile(file, dtype=np.uint16, count=HSC_Width * HSC_Height * HSC_Band)

	# Reshape the data into a 3D NumPy array
	HSC_ImageData = a.reshape(HSC_Band, HSC_Height, HSC_Width).transpose(2, 1, 0)
==========================================================================================================
If you want to use and open the koex. File with suitable software, you will need to get “Hyperspectral Image Analyzer(Version1.0) ”from the original supplier. If necessary, you can contact to web site(https://ebajapan.com/products/).

#################
#### Contact ####
#################

If you have any questions or need support, feel free to contact us (mail:indyindy@ekeio.jp / masahiro.inda@rub.de).
Department of Biosciences and Informatics,
Faculty of Science and Technology, Keio University,

Masahiro Inda,Shunsei Inoue

