RTV-reader 0.1.3

RTV file reader and visualization tools

.\RTVreader

## Required module:

- [tifffile](https://anaconda.org/channels/conda-forge/packages/tifffile/overview) __ To build .tiff

conda install conda-forge::tifffile or pip install tifffile

- [ffmpeg](https://anaconda.org/channels/conda-forge/packages/ffmpeg/overview) __ To build .mp4

conda install conda-forge::ffmpeg or pip install python-ffmpeg

- [napari](https://napari.org/stable/tutorials/fundamentals/installation.html) __ To visualize .tiff

conda install conda-forge::napari or python -m pip install "napari[all]"

# from import:

--decodeheader:    
	*"""
	Read the header of an .rtv
	All the header info are retrieved in a dict variable
	Args:
		file: Path or filename .rtv
	"""*
=> return type: **dictionary**

--getframe:
	*"""
	Retrieve a specified frame (framepos) from an RTV file
	Args:
		file: Path or filename .rtv
		framepos: Index of frame you want to retrieve
	"""*
=> return type: **np.2darray**

--getallframes:
	*"""
	Retrieve a group of frames from the same file
	Frame extracted from position start to position end
	Args:
		file: Path or filename .rtv
		start: Starting index (inclusive) \_ Optionnal
		end: Ending index (exclusive) \_ Optionnal
		If no index specified, retrieve all the frames
	"""*
=> return type: **Generator**

--normalize_files:
	*"""
	Normalize the input 'files' into a list of file paths.
	Args:
		files (str | Path | list | tuple):
			A single file path or a list/tuple of paths.
	Returns:
		list[str]: A list of file paths as strings.

	Raises:
		TypeError: If 'files' is not a valid type or contains invalid elements.

	Examples:
		>>> normalize_files("input.rtv")
		['input.rtv']

		>>> normalize_files(["a.rtv", "b.rtv"])
		['a.rtv', 'b.rtv']
	"""*
=> return **array of str**

--importRTV:
	*"""
	From multiple file, concatenate all the frames from getallframes into an numpy array
	_WARNING_ : Each file need to contain the same number of frames
	Frame extracted from position start to position end
	Args:
	files: tuples of all the RTV file name
	etart: Starting index (inclusive) _ Optionnal
	end: Ending index (exclusive) _ Optionnal
	dtype: If more precision is needed, np.float16 -> np.float32 or 64, at the cost of memory allocation
	"""*
=> return type: **np.3darray**

--readTiff:
	*"""
	To read heavy tiff file
	Arg:
		tiffname: Name of the .tiff to read
		read_metadata: If False, only retrieve the frames from the .tiff
	"""*
=> return generator of frames

--peek_and_check_gen:
	*"""
	Analize and check the coherence of a generator variable
	
	Arg:
		check_shapes : Check the shape coherence over all the frames
		show_progress : display a progression axes (tqdm)
	
	Return:
		gen: The generator itself that has been regenerated
		nframes : total number of frames (only if show_progress=True)
		shape : shape of the frames

	Pros:
		Generator is regenerated
		Free RAM consuming
	"""*
	=> return the formal generator, the number of frames and their shape

--gen_to_arr:
	*"""
	Convert a generator containing array of frames
	Automatically checking for shape coherence
	"""*
=> return the corresponding np.ndarray

# from export:

--video:
	*"""
Build a video from all of the frames, using pyplot.imshow module
Args:
    frames: np.ndarray contening the frames composing the futur video
    fps: Fix the frame per second of the video
    Imin: Fix lowest value of the color scale intensity
    Imax: Fix highest value of the color scale intensity
    Norm: To set the intensity into a log scale, use setnorm function from traitement RTV
    cmap: Choose color of the map, default is turbo

https://matplotlib.org/stable/users/explain/colors/colormaps.html dt: Time step _ Optionnel in case you want it to be displayed t_offset : Set the time offset to display. Default is 0 tunit: Optionnel, in case you want it to be displayed. Default is "ns" """* => return type: Animation

--saveTiff:
	*"""
	To export all the frames in a tiff file
	Arg:
		frames: Iterable containing data to be exported
		tiffname: Name of the .tiff to export
		compression: (Opt.) None | 'zlib' | 'lzma' \_ Zero loss compressing system proposed, from no compression to higher compression rate
		metadata: (Opt.) None | dict
		dt: (Opt.) None | float \_ Only if you want to specify the time between two frames.
		t\_offset: (Opt.) Time offset. Default is 0
		t\_unit: (Opt.) Time unit. Default is seconde
	"""*
=> return **file** in .tiff

--seeTiff:
	*"""
	To visualize heavy tiff file
	Arg:
		tiffname: Name of the .tiff to read
	"""*
=> **launch napari consol**

# from traitementRTV:

--to_1d_array:
	*"""
	Convert x into a numpy 1Dim array
	"""*
=> return **np.1darray**

--setIscale:
	*"""
	To set the intensity scale mode
	https://fr.matplotlib.net/stable/api/colors_api.html#color-norms

	Arg:
		frames: np.ndarray containing your data to scale
		scale: lin | log | symctr | asymctr | symlog. symctr correspond to CenteredNorm operation, asymctr to TwoSlopeNorm, and symlog to SymLogNorm
		Imin: Fix lowest value of the color scale intensity
		Imax: Fix highest value of the color scale intensity
		Imed: Fix the median value, only used in symctr and asymctr. Default value is 0
		linwidth: Used in symlog, correspond to linthresh define by SymLogNorm function. Default value 0.5
		linsc: Used in symlog, correspond to linscale define by SymLogNorm function. Default value 1
	"""*
=> return **Normalize** object

--subtract_backgnd:
	*"""
	A simple subtraction function that can be use to remove background
	If subtrahend is an array to which the size of 0-axis is > 1, only the mean value along this axis is considered
	WARNING : The output only return positive values. All the negative ones are clipped
	Args:
		minuend: Generally the data to be subtracted
		subtrahend: The set that is subtracting
	"""*
=> return **np.ndarray**

--setROI
    *"""
	Crops a numpy array given top-left coordinates and crop size.
	This function can be used to define a zone or region of interest, from which you want to extract data (Vertical temporal evolution for example)
	Args:
		frames: Data to reshape
		shape: (top:int, _ Starting row index
				left:int, _ Starting column index
				height:int, _ Number of row to crop
				width:int) _ Number of column to crop
	Return: cropped frames
	"""*
=> return **np.ndarray**

--centerROI:
	*"""
	Crops a numpy array given crop size.
	Args:
		frames: Data to reshape
		crop_height: height to be cropped
		crop_width: width to be cropped
	Return: centered cropped frames
	"""*
=> return **np.ndarray**

--collapse_axis:
	*"""
	Collapse one axis of an array using a specified method.
	Usually 0-axis = time, 1-axis = vertical axis| y | height, 2-axis = horizontal axis| x | width
	Can be used in the case you want to display a 2D plot from a 3D data for example, and highlight specific vertical behavior

	Args:
		data : np.ndarray _ e.g. shape (t, y, x)
		axis : int >= 0 _ Axis to collapse
		method : {'mean', 'sum', 'median', 'max', 'min'} _ Reduction method
		weights : np.ndarray, optional _ Weights for weighted mean (only for method='mean')
		normalize : bool _ Normalize result by axis length (only for method='sum')
		keepdims : bool _ Whether to keep the collapsed dimension

	Return: np.ndarray _ Collapsed array
	"""*
=> return **np.ndarray** - 1 dimension

--plot2D
	*"""
	Perfom a 2D plot using contourf matplotlib
	Args:
		frames: Data to plot, must be a 2 dimensionnal array
		x0, y0: Starting value on the x-axis (resp. y-axis), the default value is 0
		dx, dy: Spacing between x (resp. y) adjacent values, the default value is 1
		x, y: If these parameter are given, ignore previous ones (x0, y0, dx, dy)
		ax: Existing axis if there is
		cmap: Default is "turbo"
		levels: Optionnal int or array input. Set the number of minor scale, the more the smoother the image will appear
		norm: Value returned by the setIscale function
		cbar: To display the color bar scale, default is False
	Return: the ax containing the plot
	"""*
=> return **Axes** object

--add_lines
	*"""
	Add 1 or more lines to the ax
	If you only want to add just an horizontal line, just set x = your x-scale and reversly for a vertical line
	Indented to the ax scales
	lines = list of dicts:
				dict(x=..., y=..., color=..., lw=..., label=...)
	"""*
=> add ax object

--add_titles
	*"""
	Add titles where it is specified
	"""*
=> add ax object

--viewFrames
	*"""
	To visualize frames data
	Arg:
		frames: np.ndarray of data
	"""*
=> launch napari add-on