gimppaths

## gimppaths gimppaths — Operations related to paths. |

## Synopsis

    gchar**     gimp_path_list                  (gint32 image_ID,
                                                 gint *num_paths);
    gint        gimp_path_get_points            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint *path_closed,
                                                 gint *num_path_point_details,
                                                 gdouble **points_pairs);
    gchar*      gimp_path_get_current           (gint32 image_ID);
    gboolean    gimp_path_set_current           (gint32 image_ID,
                                                 const gchar *name);
    gboolean    gimp_path_set_points            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint ptype,
                                                 gint num_path_points,
                                                 const gdouble *points_pairs);
    gboolean    gimp_path_stroke_current        (gint32 image_ID);
    gint        gimp_path_get_point_at_dist     (gint32 image_ID,
                                                 gdouble distance,
                                                 gint *y_point,
                                                 gdouble *slope);
    gint        gimp_path_get_tattoo            (gint32 image_ID,
                                                 const gchar *name);
    gchar*      gimp_get_path_by_tattoo         (gint32 image_ID,
                                                 gint tattoo);
    gboolean    gimp_path_delete                (gint32 image_ID,
                                                 const gchar *name);
    gint        gimp_path_get_locked            (gint32 image_ID,
                                                 const gchar *name);
    gboolean    gimp_path_set_locked            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint lockstatus);
    gboolean    gimp_path_set_tattoo            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint tattovalue);
    gboolean    gimp_path_to_selection          (gint32 image_ID,
                                                 const gchar *name,
                                                 GimpChannelOps op,
                                                 gboolean antialias,
                                                 gboolean feather,
                                                 gdouble feather_radius_x,
                                                 gdouble feather_radius_y);
    gboolean    gimp_path_import                (gint32 image_ID,
                                                 const gchar *filename,
                                                 gboolean merge,
                                                 gboolean scale);

## Description

Operations related to paths.

## Details

### gimp_path_list ()

    gchar**     gimp_path_list                  (gint32 image_ID,
                                                 gint *num_paths);

List the paths associated with the passed image.

List the paths associated with the passed image.

`image_ID` : | The ID of the image to list the paths from.
`num_paths` : | The number of paths returned.
Returns : | List of the paths belonging to this image.

### gimp_path_get_points ()

    gint        gimp_path_get_points            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint *path_closed,
                                                 gint *num_path_point_details,
                                                 gdouble **points_pairs);

List the points associated with the named path.

List the points associated with the named path.

`image_ID` : | The ID of the image to list the paths from.
`name` : | The name of the path whose points should be listed.
`path_closed` : | Return if the path is closed. (0 = path open, 1 = path closed).
`num_path_point_details` : | The number of points returned. Each point is made up of (x, y, pnt_type) of floats.
`points_pairs` : | The points in the path represented as 3 floats. The first is the x pos, next is the y pos, last is the type of the pnt. The type field is dependant on the path type. For beziers (type 1 paths) the type can either be (1.0 = BEZIER_ANCHOR, 2.0 = BEZIER_CONTROL, 3.0 = BEZIER_MOVE). Note all points are returned in pixel resolution.
Returns : | The type of the path. Currently only one type (1 = Bezier) is supported.

### gimp_path_get_current ()

    gchar*      gimp_path_get_current           (gint32 image_ID);

The name of the current path. Error if no paths.

The name of the current path. Error if no paths.

`image_ID` : | The ID of the image to get the current path from.
Returns : | The name of the current path.

### gimp_path_set_current ()

    gboolean    gimp_path_set_current           (gint32 image_ID,
                                                 const gchar *name);

Sets the current path associated with the passed image.

Sets a named path as the current path.

`image_ID` : | The ID of the image in which a path will become current.
`name` : | The name of the path to make current.
Returns : | TRUE on success.

### gimp_path_set_points ()

    gboolean    gimp_path_set_points            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint ptype,
                                                 gint num_path_points,
                                                 const gdouble *points_pairs);

Set the points associated with the named path.

Set the points associated with the named path.

`image_ID` : | The ID of the image to set the paths in.
`name` : | The name of the path to create. If it exists then a unique name will be created - query the list of paths if you want to make sure that the name of the path you create is unique. This will be set as the current path.
`ptype` : | The type of the path. Currently only one type (1 = Bezier) is supported.
`num_path_points` : | The number of elements in the array, i.e. the number of points in the path * 3. Each point is made up of (x, y, type) of floats. Currently only the creation of bezier curves is allowed. The type parameter must be set to (1) to indicate a BEZIER type curve. Note that for BEZIER curves, points must be given in the following order: ACCACCAC... If the path is not closed the last control point is missed off. Points consist of three control points (control/anchor/control) so for a curve that is not closed there must be at least two points passed (2 x,y pairs). If (num_path_points/3) % 3 = 0 then the path is assumed to be closed and the points are ACCACCACCACC.
`points_pairs` : | The points in the path represented as 3 floats. The first is the x pos, next is the y pos, last is the type of the pnt. The type field is dependant on the path type. For beziers (type 1 paths) the type can either be (1.0 = BEZIER_ANCHOR, 2.0 = BEZIER_CONTROL, 3.0= BEZIER_MOVE). Note all points are returned in pixel resolution.
Returns : | TRUE on success.

### gimp_path_stroke_current ()

    gboolean    gimp_path_stroke_current        (gint32 image_ID);

Stroke the current path in the passed image.

Stroke the current path in the passed image.

`image_ID` : | The ID of the image which contains the path to stroke.
Returns : | TRUE on success.

### gimp_path_get_point_at_dist ()

    gint        gimp_path_get_point_at_dist     (gint32 image_ID,
                                                 gdouble distance,
                                                 gint *y_point,
                                                 gdouble *slope);

Get point on a path at a specified distance along the path.

This will return the x,y position of a point at a given distance along the bezier curve. The distance will be obtained by first digitizing the curve internally and then walking along the curve. For a closed curve the start of the path is the first point on the path that was created. This might not be obvious. Note the current path is used.

`image_ID` : | The ID of the image the paths belongs to.
`distance` : | The distance along the path.
`y_point` : | The y position of the point.
`slope` : | The slope (dy / dx) at the specified point.
Returns : | The x position of the point.

### gimp_path_get_tattoo ()

    gint        gimp_path_get_tattoo            (gint32 image_ID,
                                                 const gchar *name);

Returns the tattoo associated with the name path.

This procedure returns the tattoo associated with the specified path. A tattoo is a unique and permanent identifier attached to a path that can be used to uniquely identify a path within an image even between sessions.

`image_ID` : | The image.
`name` : | The name of the path whose tattoo should be obtained.
Returns : | The tattoo associated with the named path.

### gimp_get_path_by_tattoo ()

    gchar*      gimp_get_path_by_tattoo         (gint32 image_ID,
                                                 gint tattoo);

Return the name of the path with the given tattoo.

The procedure returns the name of the path in the specified image which has the passed tattoo. The tattoos are unique within the image and will be preserved across sessions and through renaming of the path. An error is returned if no path with the specified tattoo can be found.

`image_ID` : | The image.
`tattoo` : | The tattoo of the required path.
Returns : | The name of the path with the specified tattoo.

### gimp_path_delete ()

    gboolean    gimp_path_delete                (gint32 image_ID,
                                                 const gchar *name);

Delete the named path associated with the passed image.

Delete the named path.

`image_ID` : | The ID of the image to delete the path from.
`name` : | The name of the path to delete.
Returns : | TRUE on success.

### gimp_path_get_locked ()

    gint        gimp_path_get_locked            (gint32 image_ID,
                                                 const gchar *name);

Returns the locked status associated with the named path.

This procedure returns the lock status associated with the specified path. A path can be \"locked\" which means that the transformation tool operations will also apply to the path.

`image_ID` : | The image.
`name` : | The name of the path whose locked status should be obtained.
Returns : | The lock status associated with the name path. 0 is returned if the path is not locked. 1 is returned if the path is locked.

### gimp_path_set_locked ()

    gboolean    gimp_path_set_locked            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint lockstatus);

Set the locked status associated with the named path.

This procedure sets the lock status associated with the specified path. A path can be \"locked\" which means that the transformation tool operations will also apply to the path.

`image_ID` : | The image.
`name` : | the name of the path whose locked status should be set.
`lockstatus` : | The lock status associated with the name path. 0 if the path is not locked. 1 if the path is to be locked.
Returns : | TRUE on success.

### gimp_path_set_tattoo ()

    gboolean    gimp_path_set_tattoo            (gint32 image_ID,
                                                 const gchar *name,
                                                 gint tattovalue);

Sets the tattoo associated with the named path.

This procedure sets the tattoo associated with the specified path. A tattoo is a unique and permenant identifier attached to a path that can be used to uniquely identify a path within an image even between sessions. Note that the value passed to this function must have been obtained from a previous call to path_get_tattoo.

`image_ID` : | The image.
`name` : | the name of the path whose tattoo should be set.
`tattovalue` : | The tattoo associated with the name path. Only values returned from 'path_get_tattoo' should be used here.
Returns : | TRUE on success.

### gimp_path_to_selection ()

    gboolean    gimp_path_to_selection          (gint32 image_ID,
                                                 const gchar *name,
                                                 GimpChannelOps op,
                                                 gboolean antialias,
                                                 gboolean feather,
                                                 gdouble feather_radius_x,
                                                 gdouble feather_radius_y);

Transforms the active path into a selection

This procedure renders the desired path into the current selection.

`image_ID` : | The image.
`name` : | The name of the path which should be made into selection.
`op` : | The desired operation with current selection.
`antialias` : | Antialias selection.
`feather` : | Feather selection.
`feather_radius_x` : | Feather radius x.
`feather_radius_y` : | Feather radius y.
Returns : | TRUE on success.

### gimp_path_import ()

    gboolean    gimp_path_import                (gint32 image_ID,
                                                 const gchar *filename,
                                                 gboolean merge,
                                                 gboolean scale);

Import paths from an SVG file.

This procedure imports paths from an SVG file. This is a temporary solution until the new vectors PDB API is in place. Don't rely on this function being available in future GIMP releases.

`image_ID` : | The image.
`filename` : | The name of the SVG file to import.
`merge` : | Merge paths into a single vectors object.
`scale` : | Scale the SVG to image dimensions.
Returns : | TRUE on success.