The file is used to open a raw image file (assuming its explicit info isn’t given via the
command line) with varying possible string patterns (using regex).
When a new file is opened (via drag-and-drop, command line argument or menu), the groups
(noted as format_group) in the file are iterated in linear order (which means higher
priority should be placed at the file’s top) and a path that will “pass” all the
patterns criteria will be delegated to its proper image format handler.
Note that a pattern passes only if it’s a complete match (and not partial) and that all
the regex are case insensitive.
Also, all regex expressions start with [ and end with ] which aren’t part of the regex
expression itself:
e.g. [.*\.(yuv)$] will pass all files that end with .yuv (like nice_face.yuv).
Use ‘;’ at beginning of a line to state a comment.
The used regex engine is based on POSIX/TRE (see C++11 and TR1 references).
As regex tend to be delicate, you can use the format file logger to
identify loading errors.
Syntax:
<format_group>
file_pattern = [regex]
width = [regex],$N or some fixed value
height = [regex],$N or some fixed value
format = [regex],[A],[offset],[packing],[layout],[bpp]
format = [regex],[A],[offset],[packing],[layout],[bpp]
.
.
.
</format_group>
Format Group syntax is consisted of:
– file_pattern
The first order criteria requires that the file (should be plain file name) will
match this rule.
Place a regex pattern that will direct how to “capture” the image width, after
the regex (quoted with [] which aren’t part of the regex expression itself) put
a comma (,) and note the regex params to catch using $ and a suffix digit
(1-based, up to 9). This is non-mandatory ($1 is the default).
You can set constant values like 640 (‘width = 640’) to force a specific size.
e.g. width = [.*wh_(\d+)_\d+_.*].
This will match a file name that has ‘wh_’ somewhere in it followed by 2 integer
numbers (separated by ‘_’) and the width is the first of the 2 numbers. File name
as an example foo_img_wh_1280_720.img, img_wh_100_80_0050.raw, etc.
Follows width rules but is used to capture the image height.
e.g. height = [.*wh_\d+_(\d+)_.*]
Signs the proper image file data parsing.
Syntax:
[regex], <A?>, <ofs?>, <P|I|PI>, <((R|G|B)|(Y|U|V))+{1,3}>,<?-(8|16|32)>
[regex]
The pattern to match the format against.
[A]
Signs that the input itself comes in a ASCII text format with a CSV layout. For
user’s convenience you can place any white space, comma or semi-colon as a CSV
separator. Non-mandatory option that is useful for files created by IP tools
like Matlab and the likes.
For the special case of gray-scale image, it’s possible to give unknown image
dimensions by setting them as 1 and if the input image will carry a matrix data
form (NxM) then the dimension will be auto-detected.
[file offset]
Offset to start loading from in a file. Negative values state a reverse offset
i.e. from file’s end. This is an optional argument and can be omitted. Note
that if it is present, it’s user responsibility to know what he’s loading as
the app cannot match the format against its size for a sub-image loading.
[packing]
P stands for Planner (the components are layout one after the the other).
I stands for Interleave.
PI stands for Planner then Interleave (currently, only used with
Semi-Interleaved YUV420 format).
[layout]
Planner:
– RGB, 3 layout tokens (separated by comma) are given (any variant of RGB
i.e. RGB, RBG, BRG, BGR, GBR, GRB).
– YUV, 1 or 3 layout tokens (separated by comma) are given (any variant
of YUV). If 1, then it’s usually Y-Only format (gray/luma).
e.g. YY,U,V (YUV422 in planner layout).
Interleaved:
– RGB, 1 layout token is given, specifying the components to interleave
(left-to-right, in any order). There’s no support for RGBA (alpha channel)
as it’s uncommon in raw data.
– YUV, 1 layout token is given, specifying the components order for the
first N components (resembles Y:Cb:Cr packing). The layout is given in 1
group of up to 8 consecutive components.
Note that as YUV format dictates, the ratio between Y,U and V count must
be dividable by 2 (1 is also legit).
Planner-then-Interleaved:
– Currently, only Semi-Interleaved (a.k.a Semi-Planner) YUV420 format is
supported i.e. write as YYYYUV (or YYYYVU).
[bits-per-component]
Signs the bits-depth of each component (currently, only 8, 16 and 32 bpp are
supported). If the value is given with a minus sign (relevant only for 16, and
32) then the byte order of each component will be reversed (big-endian as
opposed to x86 native little-endian).
Note that you can supply as many formats as desired. Keep in mind the matching
order is linear and the first to match wins (still, if the file internal data will
be a miss, it will skip to the next format).
Usage tip:
For those who find the syntax a bit complex, you can find in the default format’s
file RawImageAnalyser.ini several standard examples that use some basic reg-ex commands.