SYNOPSIS: [sRet] = avine_save_video_images_to_file( string aFilenameAndPath, CoM aImages, CoS aHeaders); DESCRIPTION The Matlab external function avine_save_video_images_to_file() v1.0.0 provides a method to write a single image (represented as 2d (gray) or 3d (color rgb) matrix) or a sequence of images (represented in Matlab as cell of matrices) to a file on disk. Proprietary data formats introduced in AVINE and its predecessors (Video System 2 and 1) can be saved with this function: .imc2 (.bkc2) 1..n gray8..16 bit or color images, compressed, detailed header, XYscale .imc (.bkc) 1..n gray8..16 bit images, compressed, X=Yscale .imm 1..n gray8..16 bit images, uncompressed. X=Yscale .bkg 1 gray8..16 bit image, uncompressed An image is a two dimensional array (width and height) of pixels, in Matlab represented by a matrix of height x width. Either each pixel consist of one value (scalar, aka one component), usually referred to as 'grayscale', in Matlab represented as uint8 or uint16 data type). Or each pixel consist of three scalar values (in Matlab, it's a matrix height x width x 3 uint8) which define red, green and blue component in uint8 values of 0 to 255. Usual valid pixel value intervals are [0..255], [0..1023] or [0..4095]. RETURN-VALUE: sRet - string - empty string will be returned in case of success - will contain human readable error message in case of error PARAMETERS (M-mandatory O-optional): M aFilenameAndPath - filename (may contain path) to the file where 'images' shall be saved to M aImages - a cell of matrices containing image(s) or a single matrix (single image) O aHeaders - cell of struct with fields containing headers of each of the image(s), like returned from avine_tine_read_images or avine_load_video_images_from_file, or a single struct with fields for a single image REMARKS: - For new developments, it is recommended to save in .imc2 file format, as it is the most up to date and the most comprehensive one. - It is possible to save to .imc2 (.bkc2), .imc (.bkc), .imm and .bkg file format. - In case no file extension is given, '.imc' will be appended to file name (and imc file format will be used for saving). - If parameter 'header' is omitted: - for grayscale images, values of bits per pixel (bpp) and effective bits per pixel (ebitpp) are guessed based on the data type of the matrices (uint8 0..255 bpp=ebitpp=8, uint16 0..65535 bpp=ebitpp=16) - scale value in image file (except imc2(bkc2)) defaults to 1.000 (mm/px) - Restrictions of parameter 'images': - all matrices in the cell of matrices needs to have identical dimensions (same width and height) and data type - grayscale images are 2d matrices, data type must be mxUINT8_CLASS or mxUINT16_CLASS - color images are 3d matrices of mxUINT8_CLASS, with the third dimension requiring dimension of three (red, green, blue) - before v1.0.0, - saving of color images and saving to imc2(bkc2) files was NOT implemented - trying to save single uint16 matrix (single grayscale uint16 image) must not be done, crashes Matlab with high probability - as a workaround, matrix can be wrapped in a cell, e.g. [a, h, n] = avine_load_video_images_from_file( 'xray.imm' ); A = a{1}; %[sRet] = avine_tine_save_video_images_to_file('xray-saved', A); <- BAD b{1,1} = A; [sRet] = avine_tine_save_video_images_to_file('xray-single', b); <- OK EXAMPLES [a, h, n] = avine_load_video_images_from_file( 'xray.imm' ); [sRet] = avine_tine_save_video_images_to_file('xray-saved', a, h); [sRet] = avine_tine_save_video_images_to_file('xray-saved.imc', a); DETAILS Old-style header structure (imc, bkc, imm, bkg) >> h{1} ans = struct with fields: width: 512 height: 680 bpp: 16 [x] bpp_effective: 12 [x] scale: 0.0735 -> 0.0735 millimetre per pixel (for image height and width) Legend: [x] Taken into account Modern-style header structure (imc2, bkc2) >> h{1} ans = struct with fields: baseTag: 'VSV3' [x] cameraPortId: 188 versionTag: 1 totalLength: 2785468 [x] timestampSeconds: 1.6657e+09 [x] timestampMicroseconds: 382212 humanReadable_timestamp: '2022-10-13 2:17:18.382212 PM UTC' [x] cameraPortName: 'High3.Scr3 (Full)' [x] sourceWidth: 1360 [x] sourceHeight: 1024 [x] aoiWidth: -1 [x] aoiHeight: -1 [x] xStart: 0 [x] yStart: 0 [x] bytesPerPixel: 2 [x] effectiveBitsPerPixel: 12 [x] horizontalBinning: 0 [x] verticalBinning: 0 [x] sourceFormat: 0 humanReadable_sourceFormat: 'GRAY' [x] imageFormat: 0 humanReadable_imageFormat: 'GRAY' [x] frameNumber: 1143 [x] eventNumber: 1.5091e+09 [x] xScale: 0.0735 -> 0.0735 millimetre per pixel (for image width) [x] yScale: -1 -> -1 : unset (no scale for image height) [x] imageRotation: 0 [x] scale_x_offset: -1 [x] scale_y_offset: -1 fspare3: -1 [x] imageFlags: 39 humanReadable_imageFlags: 'LITTLE_ENDIAN LOSSLESS HORIZONTAL_FLIP_180 XYSTART_ZERO_BASED GLOBAL_TIMESTAMP' ispare1: -1 ispare2: -1 ispare3: -1 appendedFrameSize: 2785280 Legend: [x] Taken into account SEE ALSO https://avine.desy.de https://tine.desy.de/VideoSystem/vsFileFormats.html https://tine.desy.de/VideoSystem/vsAPI.html#Matlab SW Jul 25, 2023