[Olena-patches] 1840: sandbox: Continue documentation about image types and properties.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Nicolas Ballas &lt;ballas(a)lrde.epita.fr&gt; sandbox: Continue documentation about image types and properties. * sandbox/ballas/doc/image_tours.txt: update documentation. * sandbox/ballas/doc/draft.txt: New file about the images properties. draft.txt | 260 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ image_tours.txt | 160 ++++++++++++---------------------- 2 files changed, 319 insertions(+), 101 deletions(-) Index: sandbox/ballas/doc/image_tours.txt --- sandbox/ballas/doc/image_tours.txt (revision 1839) +++ sandbox/ballas/doc/image_tours.txt (working copy) @@ -7,36 +7,36 @@ ** Two types of properties - -*** Declaratif mode: (find an exemple). - +*** Declarative mode: (find an example). Here, the properties must be define by the image type programmer. They cannot be deduce from the image associated type. So we can't find the properties by -introspecting the image type (with introspection). +introspecting the image type. declaration definition ..... I check ------- ---------- | | / \ | Props | ----> | Image Type | -| | \ ___________/ +| | \ __________ / ------- -*** Automatic mode: (find an exemple). +*** Automatic mode: (find an example). Here, we get the image properties from the image associated type (site, pset...). - ----------- + ---------- / \ - | Image Type | automatic - and associated -----> Props - type - \ ___________/ + | | + | Image Type | + | and | automatic -----> Props + | associated| + | type | + \ __________ / @@ -53,36 +53,29 @@ (ex: dilatation/erosion). TODO: detail the example. -*** Implementation inherentence +*** Implementation inheritance Milena image types are property driven. It is possible to get a special behavior (not describe in the Image Concept) depends on the property define in the property associated for the image type. So, it is possible to recover some piece of interface depending on the image type properties. -For instance an Image2d has the bidimensional, and random value access. +For instance an Image2d has the bi-dimensional, and random value access. properties. Hence, Image2d automatically provides a row/column access: V at(Point2d<T>::coord x, Point2d<T>::coord y). - - *** Difference between a property and its values -*** Hierarchie of property (scalar/integer) +*** Hierarchies of property (scalar/integer) ** Implementation of properties in Milena -* Algorithm and Properties - -** Specialization - -** Static checking - -* Image Properties: +* List of the image properties: ** global Properties: + category: primary, { domain_morpher, value_morpher, identity_morpher } < morpher @@ -176,20 +169,17 @@ ** Image nD -Image on regular grid where grides nodes are points. -To gain efficienty, Images nD have a virtual borders. +Image on regular grid where grid nodes are points. +To gain efficiency, Images nD have a virtual borders. All these image are templated by T, the image value type. -*** Image1d<T> + +*** Common Associated type//properties between imageND **** Associated types: value = T -site = point1d -psite = point1d == point_<tick,int> -pset = box1d - **** Properties: --> global properties @@ -211,99 +201,56 @@ --> properties related to the pset access = random -space = one_d -size = regular +size = regular // this a global property support = aligned -**** Specific interface: - FIXME.... +*** Image1d<T> + +**** Associated types: +site = point1d +psite = point1d == point_<tick,int> +pset = box1d +**** Properties: +space = one_d +**** Specific interface: + FIXME.... *** Image2d<T> **** Associated types: -value = T - site = point2d psite = point2d == point_<square,int> pset = box2d **** Properties: ---> global properties - -category = primary -border = stored -neighb: none -data = raw -io = read_write -speed = fastest - ---> properties related to values - -// Depend on T FIXME, where the property are defined?? -kind = -quant = -value = - ---> properties related to the pset - -access = random space = two_d -size = regular -support = aligned + **** Specific interface: FIXME.... - - *** Image3d<T> **** Associated types: value = T -site = point3d -psite = point3d == point_<cube,int> -pset = box3d - **** Properties: ---> global properties - -category = primary -border = stored -neighb: none -data = raw -io = read_write -speed = fastest - ---> properties related to values - -// Depend on T FIXME, where the property are defined?? -kind = -quant = -value = - ---> properties related to the pset - -access = random space = three_d -size = regular -support = aligned **** Specific interface: FIXME.... - ** Image based on function The images based on function are templated by F and P, where @@ -355,32 +302,44 @@ **** Specific interface: FIXME.... - - - ** Run based Encoded image -All the run based encoded images have their definition domains encoded by ... -runs. These images types are not morpher types since these do not lie on -another image type. -A run is a "continuous" (note this is wrong, cf graph index) set of sites. -It is define by a site start, and a length. -All the run based encoded image are templated by P, T where P is a site type -and T a value type. - - +All the run based encoded images have their definition domains encoded by runs. +These images types are not morpher types since these do not lie on another +image type.A run is a "continuous" (note this is wrong, cf graph index) set of +sites.It is define by a site start, and a length. All the run based encoded +image are templated by P, T where P is a site type and T a value type. Note: type one shot (const)!!! Do we store the the null value in the rle encoding. (Do we compress all the images values, or only the image objects...) Is there any restriction on P and T? -Can we compress all the image types or only the point wise image type -(cf the on_the_same_line in the encode algorithm). How the properties are setted and to which values? -Depend on the PointWise property ?? + +*** Criteria needed by images to be encoded in runs + +Can we compress all the image types or only the piece wise image type +(cf the on_the_same_line in the encode algorithm). + +Currently, *encode function just work with image based on a **Point** set. +cf: +for (unsigned n = 0; same_line && n < dim - 1; ++n) + same_line = (p1[n] == p2[n]); + +Problem generalization: + A p_run take a Site as a parameter. + a p_run must be able to be casted into the Site (actually, const Site). + The only information that we have in the p_run is a len (integer). + So we must be able to refind all the site in the run from the site start, +and a addition with an integer. + + How do we name this property? + + + *** RLE Image @@ -470,7 +429,6 @@ *** Value morpher - *** Image_if ??? Index: sandbox/ballas/doc/draft.txt --- sandbox/ballas/doc/draft.txt (revision 0) +++ sandbox/ballas/doc/draft.txt (revision 0) @@ -0,0 +1,260 @@ +-*- outline -*- + +* Main image types to keep in mind + +- nD image + +- Runs image (RLE/ Sparse/ value encoded... + +- Image based on a Lut (to define) + +- graph image (see with Roland) + + +* New redefinition of the image property + + +** global Properties: + +*** Category (cf file milenadoc/tutorial/image_types.txt): + category: primary, + { domain_morpher, value_morpher, identity_morpher } < morpher + +*** Size: + + size: huge, + (large,) ? + regular + +**** Definition + The size property give us an indication about the size (in memory) taken by +the image. Indeed, an image can either huge or regular. +"huge" means that the image cannot be fully store in the ram. +"regular" means that the image can be fully store in the ram. + +**** Why does this property exist? +As we can imagine, access to a "huge" image is way slower than accessing +to "regular" image. Indeed, to access to "huge" image, we first need to load in +the ram the interesting part of the image from the hard drive. + +So, with this property, we can handle huge image in a different way in +the algorithms. (do inplace modification instead of create a new image for +instance, forbid the launch algorithm which create temporary image with huge +image...). + + + +FIXME define large? + + + +*** Border/Extended domain: + + border: none, + { stored, computed } <some + +FIXME: detail the problem, find example... + + The border property will probably change, because more information on +the border. +Actually a "border" is more extended domain of the image definition domain, +than a simple border. +The idea is an algorithm should have the same behavior for the same image with +or without an extended domain. + +problems: +If the image has stored data, but a computed border, we can do +(&ima(p)) if p is include in the image definition domain. +But we cannot do that if p is include int the image extended domain. + + + +*** Data + + data: stored, + linear < stored + raw < linear, + computed + +**** Definition + + The data property indicates how the image handle the value. +The value can be either computed (on the fly) or stored. +We say that a value is stored when we can takes a reference of it (&ima(p)) +Value stored can linear: + + | | | + v v v + -------- --------- ------------ +| | | | | | + -------- --------- ------------ + +Or they can be stored in a raw way (just in one block): + + | + v + ----------------------------------- + | | + ----------------------------------- + + +**** Note +computed data property implies that the image type has to be read_only. + + +*** io + io: read, + write, + read_only < read, + (write_only < write,) Is it useful? + read_write < both read'n write + +**** Definition + + Read/write Permissions for *ima(p)* + The name is probably bad, because image can also be accessed through +their value (ex: Run image encoded by value). + So, we should change the property name to access site_io/site_access or +something like that. + + + +*** Speed + + + speed: slow, + fast, + fastest + +**** Definition + + Give us information the time needed to access to a value from a site. + + slow: ima(p) is greater than O(1) + fast: ima(p) is in O(1) + fastest: ima(p) is in O(1) + Do we have an extended domain? + Can we access to the image value, directly with pointer in this +case? + + + + + + +** Properties related to I::value + +*** Kind + + kind: color, + gray, + label, + named < label, + logic, + mvlogic < logic && < label, + binary < mvlogic, + ternary < mvlogic + fuzzy < logic, + data, + map, + distance < map + data + +*** Quant + quant: low, + high + +*** Value + value: scalar, + vectorial, + structed, + pointer + + +** Properties related to I::pset + +*** access + + access: random, + browsing + +Does this property resume psite != site? + + + + +*** space + space: one_d, + two_d, + three_d + +Do we really need this property +If we look at the slice morpher, it must know that the input image is in 2d. +So, the answer tends to be yes. + +But in this case, how do we deal with no localized site? Specify the space +value in localization property. +Add a new value/property? + +*** support + + support: irregular, + regular + aligned < regular + +This property will certainly change. + +Support property represent the underlying support of an Image type. +It can be a grid, (regular, orthogonal, linear, isotrope, anysotrope). +It can be different from a grid (a mesh?). We also want to know the value of a +grid "stride (pas)", if this value is different from 1. Mask and convolution +directly depends on these properties. Most of the filter mask are developed to +work with grid with a stride of one. + +So, here we need to determine two things. +First, we need to know if the underling support of the image is a grid +or a mesh. Then, if the image is based on a grid we must provide an access +to the properties a grid. +We also have to choose which property of the grid are relevant, and which +property of the grid are useless. + + + + + +* Property that we need? +** has(p) + +Property that give the complexity of has(p). +-- O(1) when site = psite +-- depend on the implementation when site != psite + +** localization + + localization: none, + space, + grid < space, + regular_grid < grid + +This property should replace the support property. + +An image on a no-localized space has this property set to none. +An image on a localized space (each site can be convert into a site) has +this property set to space. +An image on a grid (which is not regular) has its property set to grid. +Does an image on a grid has always points as site? +An image based on the base grid (aligned, isotrope/anysotrop, othogonal) has +this property set to grid. + +When this property are set, you can access to new information from the image. +space -> box +regular_grid -> deltaX, deltaY of the grid + other grid property?? + + +Note: that a site can be localised without being point wise (site are localized +by vector). Do we need a property to say that the image is composed by point? +Furthermore, an image can be localized and have its type psite != site. +Ex: graph image<Point2d, T> We need a new property in order to define if the +image is localized. Is this property gives us the same information than the +support property? +