Oyranos Color Management System API - Version 0.9.6
Public Member Functions | Data Fields
oyConversion_s Struct Reference

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

#include <oyConversion_s.h>

Inheritance diagram for oyConversion_s:
Inheritance graph
Collaboration diagram for oyConversion_s:
Collaboration graph

Public Member Functions

OYAPI oyConversion_s *OYEXPORT oyConversion_New (oyObject_s object)
 allocate a new Conversion object More...
 
 oyConversion_Copy
 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_soyConversion_CreateBasicPixels (oyImage_s *input, oyImage_s *output, oyOptions_s *options, oyObject_s object)
 Allocate initialise a basic oyConversion_s object. More...
 
oyConversion_soyConversion_CreateBasicPixelsFromBuffers (oyProfile_s *p_in, oyPointer buf_in, oyPixel_t buf_type_in, oyProfile_s *p_out, oyPointer buf_out, oyPixel_t buf_type_out, oyOptions_s *options, int count)
 One dimensional color conversion context. More...
 
oyConversion_soyConversion_CreateFromImage (oyImage_s *image_in, oyOptions_s *module_options, oyProfile_s *output_profile, oyDATATYPE_e buf_type_out, uint32_t flags, oyObject_s obj)
 generate a Oyranos graph from a image file name More...
 
oyFilterGraph_soyConversion_GetGraph (oyConversion_s *conversion)
 Get the filter graph from a conversion context. More...
 
oyImage_soyConversion_GetImage (oyConversion_s *conversion, uint32_t flags)
 Get a image copy at the desired position. More...
 
oyFilterNode_soyConversion_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...
 
- Public Member Functions inherited from oyStruct_s
const char * oyStruct_GetTextFromModule (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 get object infos from a module More...
 
const char * oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 Get a text dump. More...
 
 oyStruct_RegisterStaticMessageFunc
 register a function for verbosity More...
 
 oyStruct_GetInfo
 get a additional string from a object More...
 
const char * oyStructTypeToText (oyOBJECT_e type)
 Objects type to small string. More...
 

Data Fields

const oyOBJECT_e type_
 Type of object. More...
 
oyStruct_Copy_f copy
 Copy function. More...
 
oyStruct_Release_f release
 Release function. More...
 
oyObject_s oy_
 Oyranos internal object. More...
 
- Data Fields inherited from oyStruct_s
const oyOBJECT_e type_
 Type of object. More...
 
oyStruct_Copy_f copy
 Copy function. More...
 
oyStruct_Release_f release
 Release function. More...
 
oyObject_s oy_
 Oyranos internal object. More...
 

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.

dot_inline_dotgraph_10.png

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

dot_inline_dotgraph_11.png

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.

dot_inline_dotgraph_12.png
Version
Oyranos: 0.1.8
Since
2008/06/08 (Oyranos: 0.1.8)
Date
2008/06/08
Examples:
image2pdf.c, image_display.cpp, and tutorial1.c.

Member Function Documentation

oyConversion_Copy

Copy or Reference a Conversion object.

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

Parameters
[in]conversionConversion struct object
objectNULL - means reference, the optional object triggers a real copy
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 policy filter 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 Handling
Parameters
conversionthe to be checked configuration
registrationthe to be used policy module
[in]flagsfor inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED | OY_SELECT_FILTER | OY_SELECT_COMMON
optionsoptions to the policy module
Returns
0 - indifferent, >= 1 - error
  • a message should be sent
Version
Oyranos: 0.9.6
Date
2014/06/26
Since
2009/07/24 (Oyranos: 0.1.10)
Examples:
image2pdf.c.

References oyCMMapiFilters_s::oyCMMapiFilters_Count(), oyCMMapiFilters_s::oyCMMapiFilters_Get(), oyCMMapiFilters_s::oyCMMapiFilters_Release(), oyFILTER_REG_APPLICATION, oyFILTER_REG_MODE_STRIP_IMPLEMENTATION_ATTR, 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]inputthe input image data
[in]outputthe output image data
[in]optionsoptions 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. OY_DEFAULT_CMM_CONTEXT and OY_DEFAULT_CMM_RENDERER can contain string to explicitely select the icc module.
objectthe optional object
Returns
the conversion context
Version
Oyranos: 0.9.6
Date
2014/06/29
Since
2008/06/26 (Oyranos: 0.1.8)
Examples:
image2pdf.c.

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

Referenced by oyConversion_CreateBasicPixelsFromBuffers().

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

One dimensional color 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.

Parameters
[in]p_inthe input profile
[in]buf_inthe input channels
[in]buf_type_inthe input pixel type; channel count can be omitted
[in]p_outthe output profile
[in]buf_outthe output channels
[in]buf_type_outthe output pixel type; channel count can be omitted
[in]optionssee the same option in oyConversion_CreateBasicPixels()
[in]countthe pixel count to convert in buf_in and buf_out
Returns
the conversion context
Version
Oyranos: 0.9.5
Date
2014/02/05
Since
2011/02/22 (Oyranos: 0.3.0)
Examples:
tutorial1.c.

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

oyConversion_s * oyConversion_CreateFromImage ( oyImage_s image_in,
oyOptions_s module_options,
oyProfile_s output_profile,
oyDATATYPE_e  buf_type_out,
uint32_t  flags,
oyObject_s  obj 
)

generate a Oyranos graph from a image file name

Function oyConversion_CreateFromImage

Parameters
[in]image_ininput
[in]module_optionsoptions for icc node
[in]output_profileprofile to convert colors to;
[in]buf_type_outthe desired data type for output
[in]flagsfor inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED | OY_SELECT_FILTER | OY_SELECT_COMMON
[in]objOyranos object (optional)
Returns
generated new graph, owned by caller
Version
Oyranos: 0.9.6
Date
2014/07/01
Since
2012/04/21 (Oyranos: 0.5.0)

References OY_CMM_STD, OY_TYPE_STD, oyChannels_m, oyConversion_Correct(), oyConversion_New(), oyConversion_Set(), oyDataType_m, oyFilterNode_s::oyFilterNode_Connect(), oyFilterNode_s::oyFilterNode_FromOptions(), oyFilterNode_s::oyFilterNode_NewWith(), oyFilterNode_s::oyFilterNode_SetData(), oyImage_s::oyImage_Create(), oyImage_s::oyImage_GetHeight(), oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_GetProfile(), oyImage_s::oyImage_GetWidth(), oyLAYOUT, oyOptions_s::oyOptions_Release(), oyProfile_s::oyProfile_GetChannelsCount(), and oyToChannels_m.

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]conversionconversion 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 oyFilterGraph_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]conversionconversion object
[in]flagsOY_INPUT or OY_OUTPUT
Returns
the image
Version
Oyranos: 0.1.10
Since
2009/02/19 (Oyranos: 0.1.10)
Date
2009/02/19
Examples:
image_display.cpp.

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_s::oyImage_FromFile().

oyFilterNode_s * oyConversion_GetNode ( oyConversion_s conversion,
uint32_t  flags 
)

Get the filter node copy.

Function oyConversion_GetNode

Parameters
[in,out]conversionconversion object
[in]flagsOY_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
Examples:
image_display.cpp.

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]conversionconversion object
[in]xposition x
[in]yposition y
[in,out]pixel_accesspixel 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_s::oyImage_FromFile(), and oyImage_s::oyImage_ToFile().

OYAPI int OYEXPORT oyConversion_Release ( oyConversion_s **  conversion)

release and possibly deallocate a oyConversion_s object

Function oyConversion_Release

Parameters
[in,out]conversionConversion struct object
Examples:
image2pdf.c, and image_display.cpp.

References oyOBJECT_CONVERSION_S.

Referenced by oyConversion_CreateBasicPixels(), oyImage_s::oyImage_FromFile(), and oyImage_s::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 );
}
Parameters
[in,out]conversionconversion object
[in,out]pixel_accessoptional pixel iterator configuration
Returns
0 on success, else error
Version
Oyranos: 0.1.10
Since
2008/07/06 (Oyranos: 0.1.8)
Date
2009/03/06
Examples:
image2pdf.c, and tutorial1.c.

References oy_debug, oyArray2d_s::oyArray2d_Release(), oyConversion_GetImage(), oyConversion_GetNode(), oyFilterGraph_s::oyFilterGraph_PrepareContexts(), oyFilterGraph_s::oyFilterGraph_SetFromNode(), oyFilterNode_s::oyFilterNode_GetPlug(), oyFilterPlug_s::oyFilterPlug_Release(), oyFilterPlug_s::oyFilterPlug_ResolveImage(), oyImage_s::oyImage_FillArray(), oyImage_s::oyImage_ReadArray(), oyImage_s::oyImage_Release(), oyImage_s::oyImage_RoiToSamples(), oyImage_s::oyImage_SamplesToPixels(), oyOBJECT_CONVERSION_S, oyObject_GetId(), oyOBJECT_RECTANGLE_S, oyOptions_s::oyOptions_FindString(), oyPIXEL_ACCESS_IMAGE, oyPixelAccess_s::oyPixelAccess_Create(), oyPixelAccess_s::oyPixelAccess_Release(), oyPixelAccess_s::oyPixelAccess_SetArrayFocus(), oyPixelAccess_s::oyPixelAccess_Show(), oyRectangle_s::oyRectangle_Release(), oyRectangle_s::oyRectangle_SetByRectangle(), and oyRectangle_s::oyRectangle_Show().

Referenced by oyImage_s::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]conversionconversion object
[in]inputinput node
[in]outputoutput 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_s::oyImage_FromFile(), and oyImage_s::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]conversionconversion object
[in]head_linetext for inclusion
[in]reservedfuture format selector (dot, xml ...)
[in]allocateFuncallocation 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(), oyFilterGraph_s::oyFilterGraph_SetFromNode(), oyFilterGraph_s::oyFilterGraph_ToText(), and oyOBJECT_CONVERSION_S.

Field Documentation

oyStruct_Copy_f oyConversion_s::copy

Copy function.

oyObject_s oyConversion_s::oy_

Oyranos internal object.

Features name and hash. Do not change during object life time.

oyStruct_Release_f oyConversion_s::release

Release function.

const oyOBJECT_e oyConversion_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.