RTV-reader 0.1.4.1
RTV file reader and visualization tools
Requires Python: >=3.9

.\\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