| Oyranos Colour Management System API

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

Public Member Functions | Data Fields
oyConversion_s Struct Reference
DAG and Image processing API

A filter chain or graph to manipulate a image. More...

`#include <oyConversion_s.h>`

Inheritance diagram for oyConversion_s:
Collaboration diagram for oyConversion_s:

## Public Member Functions
OYAPI oyConversion_s *OYEXPORT | oyConversion_New (oyObject_s object)
| allocate a new Conversion object More...
OYAPI oyConversion_s *OYEXPORT | oyConversion_Copy (oyConversion_s *conversion, oyObject_s object)
| copy or reference a Conversion object More...
OYAPI int OYEXPORT | oyConversion_Release (oyConversion_s **conversion)
| release and possibly deallocate a oyConversion_s object More...
int | oyConversion_Correct (oyConversion_s *conversion, const char *registration, uint32_t flags, oyOptions_s *options)
| Check for correctly adhering to policies. More...
oyConversion_s * | oyConversion_CreateBasicPixels (oyImage_s *input, oyImage_s *output, oyOptions_s *options, oyObject_s object)
| Allocate initialise a basic oyConversion_s object. More...
oyConversion_s * | oyConversion_CreateBasicPixelsFromBuffers (oyProfile_s *p_in, oyPointer buf_in, oyDATATYPE_e buf_type_in, oyProfile_s *p_out, oyPointer buf_out, oyDATATYPE_e buf_type_out, oyOptions_s *options, int count)
| One dimensional colour conversion context. More...
oyFilterGraph_s * | oyConversion_GetGraph (oyConversion_s *conversion)
| Get the filter graph from a conversion context. More...
oyImage_s * | oyConversion_GetImage (oyConversion_s *conversion, uint32_t flags)
| Get a image copy at the desired position. More...
oyFilterNode_s * | oyConversion_GetNode (oyConversion_s *conversion, uint32_t flags)
| Get the filter node copy. More...
int | oyConversion_GetOnePixel (oyConversion_s *conversion, double x, double y, oyPixelAccess_s *pixel_access)
| Compute one pixel at the given position. More...
int | oyConversion_RunPixels (oyConversion_s *conversion, oyPixelAccess_s *pixel_access)
| Iterate over a conversion graph. More...
int | oyConversion_Set (oyConversion_s *conversion, oyFilterNode_s *input, oyFilterNode_s *output)
| Set input and output of a conversion graph. More...
char * | oyConversion_ToText (oyConversion_s *conversion, const char *head_line, int reserved, oyAlloc_f allocateFunc)
| Text description of a conversion graph. More...
int | oyPixelAccess_ChangeRectangle (oyPixelAccess_s *pixel_access, double start_x, double start_y, oyRectangle_s *output_rectangle)
| Change the ticket for a conversion graph. More...
Public Member Functions inherited from oyStruct_s
const char * | oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
| get a text dump More...

## Data Fields
oyStruct_Copy_f | copy
oyStruct_Release_f | release
Data Fields inherited from oyStruct_s
oyStruct_Copy_f | copy
oyStruct_Release_f | release

## Detailed Description

A filter chain or graph to manipulate a image.

Order of filters matters. The processing direction is a bit like raytracing as nodes request their parent.

The graph is allowed to be a directed graph without cycles.

oyConversion_s shall provide access to the graph and help in processing and managing nodes.

Creating Graphs:
Most simple is to use the oyConversion_CreateBasicPixels() function to create a profile to profile and possible image buffer to image buffer linear graph.
The other possibility is to create a non linear graph. The input member can be accessed for this directly.

While it would be possible to have several open ends in a graph, there are two endpoints considered as special. The input member prepresents the top most required node to be provided in a oyConversion_s graph. The input node is accessible for user manipulation. The other one is the out_ member. It is the closing node in the graph. It will be set by Oyranos during closing the graph.

Using Graphs:
To obtain the data the oyConversion_RunPixels() and oyConversion_GetOnePixel() functions are available.

Version
  Oyranos: 0.1.8

Since
  2008/06/08 (Oyranos: 0.1.8)

Date
  2008/06/08

## Member Function Documentation

OYAPI oyConversion_s *OYEXPORT oyConversion_Copy | ( | oyConversion_s * | conversion,
|  | oyObject_s | object
| ) |  |

copy or reference a Conversion object

Function oyConversion_Copy

The function is for copying and for referencing. The reference is the most often used way, which saves resourcs and time.

Parameters

  [in] | conversion | Conversion struct object
  | object | NULL - means reference, the optional object triggers a real copy

References oyOBJECT_CONVERSION_S.

int oyConversion_Correct | ( | oyConversion_s * | conversion,
|  | const char * | registration,
|  | uint32_t | flags,
|  | oyOptions_s * | options
| ) |  |

Check for correctly adhering to policies.

Function oyConversion_Correct

Without any options the module selected with the registration argument shall perform graph analysis and correct the graph.

Typical Options:
  - "command"-"help" - a string option issuing a help text as message
  - "verbose" - reporting changes as message

TODO: display and selection of policy modules

See also
  Defaults API

Parameters

  | conversion | the to be checked configuration
  | registration | the to be used policy module
  [in] | flags | for inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED | OY_SELECT_FILTER | OY_SELECT_COMMON
  | options | options to the policy module

Returns
  0 - indifferent, >= 1 - error
  - a message should be sent

Version
  Oyranos: 0.1.10

Since
  2009/07/24 (Oyranos: 0.1.10)

Date
  2009/07/24

References oyFILTER_REG_TYPE, oyFilterRegistrationMatch(), oyFilterRegistrationToText(), oyOBJECT_CMM_API9_S, and oyOBJECT_CONVERSION_S.

Referenced by oyConversion_CreateFromImage().

oyConversion_s * oyConversion_CreateBasicPixels | ( | oyImage_s * | input,
|  | oyImage_s * | output,
|  | oyOptions_s * | options,
|  | oyObject_s | object
| ) |  |

Allocate initialise a basic oyConversion_s object.

Function oyConversion_CreateBasicPixels

Provided options will be passed to oyFilterNode_NewWith(). There for no options defaults will be selected.

Parameters

  [in] | input | the input image data
  [in] | output | the output image data
  [in] | options | options to be passed to oyFilterCore_s Each option should be carefully named to be correctly selected by the intented filter (root, icc and output). The available options are particial defined by plugable policy modules, e.g. "oicc", and a filters own options.
  | object | the optional object

Returns
  the conversion context

Version
  Oyranos: 0.1.10

Since
  2008/06/26 (Oyranos: 0.1.8)

Date
  2009/08/01

References oyConversion_New(), oyConversion_Release(), oyConversion_Set(), oyFilterNode_s::oyFilterNode_Connect(), oyFilterNode_s::oyFilterNode_NewWith(), and oyFilterNode_s::oyFilterNode_SetData().

Referenced by oyConversion_CreateBasicPixelsFromBuffers().

oyConversion_s * oyConversion_CreateBasicPixelsFromBuffers | ( | oyProfile_s * | p_in,
|  | oyPointer | buf_in,
|  | oyDATATYPE_e | buf_type_in,
|  | oyProfile_s * | p_out,
|  | oyPointer | buf_out,
|  | oyDATATYPE_e | buf_type_out,
|  | oyOptions_s * | options,
|  | int | count
| ) |  |

One dimensional colour conversion context.

Function oyConversion_CreateBasicPixelsFromBuffers

The options are passed to oyConversion_CreateBasicPixels(); The function does the lookups for the profiles and the modules contexts in the Oyranos cache on the fly.

Version
  Oyranos: 0.3.0

Since
  2011/02/22 (Oyranos: 0.3.0)

Date
  2011/02/22

References oyChannels_m, oyConversion_CreateBasicPixels(), oyDataType_m, oyImage_s::oyImage_Create(), oyImage_s::oyImage_Release(), and oyProfile_s::oyProfile_GetChannelsCount().

oyFilterGraph_s * oyConversion_GetGraph | ( | oyConversion_s * | conversion | ) |

Get the filter graph from a conversion context.

Function oyConversion_GetGraph

See also
  oyFilterGraph_GetNode() to obtain a node.

Parameters

  [in,out] | conversion | conversion object

Returns
  the filter graph containing all nodes

Version
  Oyranos: 0.2.1

Since
  2011/01/02 (Oyranos: 0.2.1)

Date
  2011/01/02

References oyFilterNode_s::oyFilterGraph_FromNode().

oyImage_s * oyConversion_GetImage | ( | oyConversion_s * | conversion,
|  | uint32_t | flags
| ) |  |

Get a image copy at the desired position.

Function oyConversion_GetImage

Parameters

  [in,out] | conversion | conversion object
  [in] | flags | OY_INPUT or OY_OUTPUT

Returns
  the image

Version
  Oyranos: 0.1.10

Since
  2009/02/19 (Oyranos: 0.1.10)

Date
  2009/02/19

References oyFilterNode_s::oyFilterNode_GetPlug(), oyFilterNode_s::oyFilterNode_GetSocket(), oyFilterPlug_s::oyFilterPlug_Release(), oyFilterSocket_s::oyFilterSocket_Release(), oyImage_s::oyImage_Copy(), oyOBJECT_CONVERSION_S, oyPIXEL_ACCESS_IMAGE, oyPixelAccess_s::oyPixelAccess_Create(), and oyPixelAccess_s::oyPixelAccess_Release().

Referenced by oyConversion_RunPixels(), and oyImage_FromFile().

oyFilterNode_s * oyConversion_GetNode | ( | oyConversion_s * | conversion,
|  | uint32_t | flags
| ) |  |

Get the filter node copy.

Function oyConversion_GetNode

Parameters

  [in,out] | conversion | conversion object
  [in] | flags | OY_INPUT or OY_OUTPUT

Returns
  the filter node as defined by flags

Version
  Oyranos: 0.3.0

Since
  2011/03/27 (Oyranos: 0.3.0)

Date
  2011/03/29

References oyFilterNode_s::oyFilterNode_Copy(), and oyOBJECT_CONVERSION_S.

Referenced by oyConversion_RunPixels().

int oyConversion_GetOnePixel | ( | oyConversion_s * | conversion,
|  | double | x,
|  | double | y,
|  | oyPixelAccess_s * | pixel_access
| ) |  |

Compute one pixel at the given position.

Function oyConversion_GetOnePixel

Parameters

  [in,out] | conversion | conversion object
  [in] | x | position x
  [in] | y | position y
  [in,out] | pixel_access | pixel iterator configuration

Returns
  -1 end; 0 on success; error > 1

Version
  Oyranos: 0.3.0

Since
  2008/07/14 (Oyranos: 0.1.8)

Date
  2011/04/11

References oyFilterNode_s::oyFilterNode_GetPlug(), and oyFilterPlug_s::oyFilterPlug_Release().

OYAPI oyConversion_s *OYEXPORT oyConversion_New | ( | oyObject_s | object | ) |

allocate a new Conversion object

Function oyConversion_New

References oyOBJECT_OBJECT_S.

Referenced by oyConversion_CreateBasicPixels(), oyConversion_CreateFromImage(), oyImage_FromFile(), and oyImage_ToFile().

OYAPI int OYEXPORT oyConversion_Release | ( | oyConversion_s ** | conversion | ) |

release and possibly deallocate a oyConversion_s object

Function oyConversion_Release

Parameters

  [in,out] | conversion | Conversion struct object

References oyOBJECT_CONVERSION_S.

Referenced by oyConversion_CreateBasicPixels(), oyImage_FromFile(), and oyImage_ToFile().

int oyConversion_RunPixels | ( | oyConversion_s * | conversion,
|  | oyPixelAccess_s * | pixel_access
| ) |  |

Iterate over a conversion graph.

Function oyConversion_RunPixels

        // use the output
        oyConversion_RunPixels( context, NULL );
        oyImage_s * image = oyConversion_GetImage( context, OY_OUTPUT );
        // get the data and draw the image
        for(i = 0; i < image->height; ++i)
        {
          image_data = oyImage_GetLineF(image)( image, i, &height, -1, &is_allocated );

          // ...

          if(is_allocated)
            free( image_data );
        }

    @param[in,out] conversion          conversion object
    @param[in,out] pixel_access        optional pixel iterator configuration
    @return                            0 on success, else error

    @version Oyranos: 0.1.10
    @since   2008/07/06 (Oyranos: 0.1.8)
    @date    2009/03/06

References oyArray2d_s::oyArray2d_Release(), oyConversion_GetImage(), oyConversion_GetNode(), oyFilterGraph_s::oyFilterGraph_PrepareContexts(), oyFilterNode_s::oyFilterGraph_SetFromNode(), oyFilterNode_s::oyFilterNode_GetPlug(), oyFilterNodes_s::oyFilterNodes_Count(), oyFilterPlug_s::oyFilterPlug_Release(), oyFilterPlug_s::oyFilterPlug_ResolveImage(), oyImage_s::oyImage_FillArray(), oyImage_s::oyImage_ReadArray(), oyImage_s::oyImage_Release(), oyOBJECT_CONVERSION_S, oyOBJECT_RECTANGLE_S, oyOptions_s::oyOptions_FindString(), oyPIXEL_ACCESS_IMAGE, oyPixelAccess_s::oyPixelAccess_Create(), oyPixelAccess_s::oyPixelAccess_Release(), and oyRectangle_s::oyRectangle_SetByRectangle().

Referenced by oyImage_ToFile().

int oyConversion_Set | ( | oyConversion_s * | conversion,
|  | oyFilterNode_s * | input,
|  | oyFilterNode_s * | output
| ) |  |

Set input and output of a conversion graph.

Function oyConversion_Set

Parameters

  [in,out] | conversion | conversion object
  [in] | input | input node
  [in] | output | output node

Returns
  0 on success, else error

Version
  Oyranos: 0.1.10

Since
  2009/03/05 (Oyranos: 0.1.10)

Date
  2009/03/05

References oyOBJECT_CONVERSION_S.

Referenced by oyConversion_CreateBasicPixels(), oyConversion_CreateFromImage(), oyImage_FromFile(), and oyImage_ToFile().

char * oyConversion_ToText | ( | oyConversion_s * | conversion,
|  | const char * | head_line,
|  | int | reserved,
|  | oyAlloc_f | allocateFunc
| ) |  |

Text description of a conversion graph.

Function oyConversion_ToText

Todo:
  Should this function generate XFORMS compatible output? How?

Parameters

  [in] | conversion | conversion object
  [in] | head_line | text for inclusion
  [in] | reserved | future format selector (dot, xml ...)
  [in] | allocateFunc | allocation function

Returns
  the graph description

Version
  Oyranos: 0.1.8

Since
  2008/10/04 (Oyranos: 0.1.8)

Date
  2009/03/05

References oyFilterGraph_s::oyFilterGraph_New(), oyFilterGraph_s::oyFilterGraph_Release(), oyFilterNode_s::oyFilterGraph_SetFromNode(), oyFilterGraph_s::oyFilterGraph_ToText(), and oyOBJECT_CONVERSION_S.

int oyPixelAccess_ChangeRectangle | ( | oyPixelAccess_s * | pixel_access,
|  | double | start_x,
|  | double | start_y,
|  | oyRectangle_s * | output_rectangle
| ) |  |

Change the ticket for a conversion graph.

Function oyPixelAccess_ChangeRectangle

Parameters

  [in,out] | pixel_access | optional pixel iterator configuration
  [in] | start_x | x position relative to virtual source image
  [in] | start_y | y position relative to virtual source image
  [in] | output_rectangle | the region in the output image, optional

Returns
  0 on success, else error

Version
  Oyranos: 0.3.0

Since
  2011/04/17 (Oyranos: 0.3.0)

Date
  2011/05/ß5

References oyRectangle_s::oyRectangle_New(), oyRectangle_s::oyRectangle_Release(), and oyRectangle_s::oyRectangle_SetByRectangle().

## Field Documentation

oyStruct_Copy_f oyConversion_s::copy

copy function

oyStruct_Release_f oyConversion_s::release

release function