Overview

The algorithm that I show here is based on the algorithm presented in “Efficient clipping of arbitrary polygons” by Günther Greiner and Kai Hormann. My algorithm is adapted to work on closed bezier paths (instead of polygons), handle nonintersecting (sub)paths, and handle intersections between fill paths and hole paths.

As before the full source code is available on Bitbucket, and it’s licensed under the MIT license. If you want to follow along, the majority of the algorithms described are implemented in the FBBezierGraph class.

Data Structures

My algorithm, like Greiner-Hormann’s, uses several data structures. The primary is FBBezierGraph. Think of FBBezierGraph as an expanded version of NSBezierPath that can be annotated with where intersections happen. FBBezierGraph contains FBBezierContours, which are just closed subpaths. Anytime I see a moveto in a NSBezierPath, that’s a new contour. FBBezierContours in turn contain FBContourEdges, which are mainly wrappers around a FBBezierCurve. They represent one cubic bezier curve, and can also hold FBEdgeCrossings. Each FBEdgeCrossing represents a location where another edge crosses this edge.

By breaking a NSBezierPath out into all these separate structures, it makes it easier to process. Contours need to be dealt with one at a time, and I need a way to keep track of where the intersections happen. The basic flow is to convert my NSBezierPath into a FBBezierGraph, perform the boolean operation, then convert it back to a NSBezierPath. FBBezierGraph handles both sides of the conversion.

Basic Algorithm

The basic algorithm for union, intersect, and difference are very similar. In fact, there’s only one step that’s all that different between the three. The basic steps are:

1. Find all the intersections where the edges actually cross, and insert FBEdgeCrossings into both FBBezierGraphs at those locations.

2. Handle all the intersecting contours.

   • Walk each contour and mark the entry and exit into the section I want to output to the final result.

   • Walk each contour and output the final contours by following the entry and exit directions marked in the previous step.

3. Handle all the nonintersecting contours.

Step three is the only step that is very different between the operations. Step two is identical except for if we mark the inside or outside section.

The above algorithm only applies to union, intersect, and difference. On the other hand, the entire implementation for exclusive or is:

- (FBBezierGraph *) xorWithBezierGraph:(FBBezierGraph *)graph
{
    FBBezierGraph *allParts = [self unionWithBezierGraph:graph];
    FBBezierGraph *intersectingParts = [self intersectWithBezierGraph:graph];
    return [allParts differenceWithBezierGraph:intersectingParts];
}

As I’ve mentioned previously, exclusive or is implemented in terms of union, intersect and difference. I’ll now ignore exclusive or for the rest of the post.

Finding Crossings

For all three operations I start the same way: finding all the intersections where the edges cross. I do this by simply walking each edge of the subject bezier graph and intersecting them with the edges of the clipping graph. I don’t look for self intersections. I insert a FBEdgeCrossing into each bezier graph for each intersection, and point the crossings at each other so I can easily jump between graphs at crossings. You can find the code for this in the insertCrossingsWithBezierGraph: method.

There are a couple of things I have to look out for when determining if two edges actually cross at an intersection. One possibility is that the two edges are tangent at the intersection, and don’t cross. That is straightforward to detect; I compute the tangent for both curves at the intersection point, and see if they’re parallel. If they are, then they are tangent at that point.

The more involved case is when the intersection happens at the end point of one or both of the edges. If an intersection happens in the interior of two curves, and it’s not tangent, then I know the edges actually cross. But suppose I encounter the following intersection:

I don’t know if the two contours cross or not just by looking at these two edges alone. I need to look at the next edge. There are two basic possibilities:

Either the contours cross at the intersection, or they don’t (I consider going coincident to be not crossing). I use the tangents at the intersection point to determine if the contours actually cross or not. The tangents for the above examples look something like:

I then compute the angles of the tangents by computing the polar coordinates. If the contours cross, the angles will cross as well. The method doesEdge:crossEdge:atIntersection: implements the crossing check.

When finding crossings I have to be wary of one additional problem caused by intersections at end points. Since the end of one edge is the start of the next, an intersection at the end point will be found on both edges, resulting in duplicate crossings. So when I’m done finding all the crossings, I’ll go through the crossings I found and remove the duplicates.

Intersecting Contours

I take the processing of intersecting contours in two steps: marking which sections (inside or outside) of each contour to output, and then creating a new bezier graph containing those sections. The code for doing this for all three boolean operations is:

    [self markCrossingsAsEntryOrExitWithBezierGraph:graph markInside:NO];
    [graph markCrossingsAsEntryOrExitWithBezierGraph:self markInside:NO];

    FBBezierGraph *result = [self bezierGraphFromIntersections];

This is the code from the union operation. The code for the intersect and difference operations are identical except for the values passed in to the markInside parameter. Intersect passes YES for both self and graph, while difference passes NO for self and YES for graph (marking the outside of self and inside of graph).

When I mark the crossings as entry or exit, I go one contour at a time and mark the entries and exits relative to the other contour crossing it:

- (void) markCrossingsAsEntryOrExitWithBezierGraph:(FBBezierGraph *)otherGraph markInside:(BOOL)markInside
{
    for (FBBezierContour *contour in self.contours) {
        NSArray *intersectingContours = contour.intersectingContours;
        for (FBBezierContour *otherContour in intersectingContours) {
            if ( otherContour.inside == FBContourInsideHole )
                [contour markCrossingsAsEntryOrExitWithContour:otherContour markInside:!markInside];
            else
                [contour markCrossingsAsEntryOrExitWithContour:otherContour markInside:markInside];
        }
    }
}

Above I check to see if the other contour I’m intersecting with is a hole or not. As I talked about in the previous post, if the other contour is a hole, then I want to mark the opposite section that I normally would for this operation.

The method markCrossingsAsEntryOrExitWithContour:markInside: does the actual marking of crossings as entry or exit. The pseudocode for marking entries and exists:

1. I pick a point on the contour to start with.

2. I determine if the point lies inside or outside the other contour, using the even odd rule.

3. Using the markInside parameter and if the start point is inside or outside, I determine if the start point is in the section I want to output or not.

   1. If the start point is in the right section already, the next crossing will be an exit, so assign isNextCrossingAnEntry = NO.

   2. If the start point is not in the section I want to output, the next crossing will be an entry, so I assign isNextCrossingAnEntry = YES.

4. For each crossing on the contour (starting with my start point and proceeding in order):

   1. Assign the crossing’s property isEntry = isNextCrossingAnEntry.

   2. Toggle the value of isNextCrossingAnEntry.

The only tricky part of this is choosing a good start point. I don’t want a start point that is ambiguous, like one that is on the other contour.

After I’m done marking all the crossings as entry or exit, I need to build the final contours. The algorithm for that is:

1. While there are unprocessed crossings do:

   1. I find the first unprocessed crossing on the bezier graph.

   2. I create a new contour.

   3. While the current crossing hasn’t be processed do:

      1. If the crossing is an entry, I move forward through the contour adding the edges (or edge segment if there’s a crossing) until I encounter the next crossing.

      2. Else the crossing is an exit, and I move backwards through the contour, adding edges (or segments) until I encounter the next crossing.

      3. I switch to the other bezier graph by setting the current crossing to it’s counterpart.

   4. I add the new contour to the final bezier graph.

And now I’m done processing all the intersecting contours.

Nonintersecting Contours

The final part of a boolean operation is dealing with the nonintersecting contours. This is where the various boolean operations differ the most. I start with the list of contours that don’t intersect anything.

For the union operation, I start out optimistically and assume they’ll all end up in the final result. I then walk both bezier graph’s nonintersecting contours and see if an individual contour is inside (as defined by the even odd rule) the opposite bezier graph. If it is, I know it’s redundant and I remove it from the final contours.

The code looks something like:

    for (FBBezierContour *ourContour in ourNonintersectingContours) {
        if ( [graph containsContour:ourContour] )
            [finalNonintersectingContours removeObject:ourContour];
    }
    for (FBBezierContour *theirContour in theirNonintersectinContours) {
        if ( [self containsContour:theirContour] )
            [finalNonintersectingContours removeObject:theirContour];
    }

Intersect is more or less the opposite of union. I start by assuming none of the nonintersecting contours from either bezier graph will make it. I then walk all the nonintersecting contours and see if the opposite bezier graph contains them. If the opposite graph does, then there is overlap, and the overlap is the contour being contained.

A simplified version of the code for intersect is:

    for (FBBezierContour *ourContour in ourNonintersectingContours) {
        if ( graph containsContour:ourContour] )
            [finalNonintersectingContours addObject:ourContour];
    }
    for (FBBezierContour *theirContour in theirNonintersectinContours) {
        if ( [self containsContour:theirContour] )
            [finalNonintersectingContours addObject:theirContour];
    }

I start computing the difference for nonintersecting contours by assuming none will make it into the final result. I then walk the nonintersecting contours for the subject bezier graph. If they are not contained by (and thus not subtracted away) the clipping bezier graph, I add them to the final contours. Next I walk the nonintersecting contours for the clipping bezier graph. If they are contained by the subject bezier graph, that means they cut a hole in the subject, so I add them to final contours.

The code looks kind of like:

    for (FBBezierContour *ourContour in ourNonintersectingContours) {
        if ( ![graph containsContour:ourContour] )
            [finalNonintersectingContours addObject:ourContour];
    }
    for (FBBezierContour *theirContour in theirNonintersectinContours) {
        if ( [self containsContour:theirContour] )
            [finalNonintersectingContours addObject:theirContour]; // add it as a hole
    }

And with that I’m done. I have the final intersecting and nonintersecting contours and can convert the bezier graph back into a NSBezierPath.

Contour Containment Issues

In the previous section, I skipped over the implementation of the containsContour: method despite the fact it gave me fits in practice. In theory it should be easy to implement: I pick a point on the contour and use the even odd rule to see if the point is inside the other bezier graph or not. Unfortunately there are two situations which make it not as simple as I’d hoped.

The first problem is easiest seen:

Does the blue contour contain the red? In both cases the even odd rule returns one intersection, indicating that it does. However, just by looking at it, I can tell that in the diagram on the right, it doesn’t. The problem is the ray passes through an edge where both contours coincide.

The second problem is show below:

This one is a bit more subtle. Notice that the ray I’m using to determine even or odd intersects where two edges meet. This means I’ll find two intersections (one for each edge) instead of just one, and I’ll think the red square is outside the blue circle.

My solution is somewhat brute force. I actually ended up casting a full line through the entire contour, instead of just one side, in order to increase my chances of getting a useful ray. I also alternate between horizontal and vertical lines, and I loop until I get a line that is unambiguous. There is more code dedicated to this operation that I like. There is probably a better way to do this.

Conclusion

I took on this project mainly for my own benefit, so I could learn how this works. But hopefully you’ve learned something useful too amidst all my struggling with this.

I have tried to test the sample code the best I could. You can check out all the test cases under the “Shapes” menu in the sample application. However, I’ve undoubtedly missed or left out edge cases which will cause the code to fail. If you decide to use this code in a commercial application: test, test, test. If you do find a case my code doesn’t handle, I’d like to hear about. That said, the code is provided as is, and I’m not guaranteeing any support for it.

Conceptually Speaking

I think it’s helpful to start out with a simple case and see how this will work conceptually. I’ll start with the following example:

Here I have a rectangle and circle overlapping. The intersections have already been calculated and circled in green. Now I consider the shapes as wireframes:

In my head, I divide up each path into sections based on the intersection points. There are two kinds of sections: one that is outside the other path, and one that is inside the other path. Performing a boolean operation is just a matter of picking the correct section from each path.

Here I’ve used a dashed style to mark which parts of the path are inside of the other path. Once I’ve separated the paths into the inside and outside parts, it’s easy to perform the boolean operations conceptually.

A union is a logical or, so I want all the outside sections:

The intersect operation is a logical and, so I just want the inside sections:

Difference is where I take a path and remove the parts that intersect with the other path. For that I want the outside sections of the subject (the rectangle), and the inside sections of the clip (the circle):

For now I’m going to ignore logical exclusive or because it requires properly handling subpaths and holes, which I’m not ready to talk about just yet. However I will say that exclusive or isn’t a primitive like the other operations, but is defined in terms of union, intersect, and difference. Specifically A Xor B is defined as (A Union B) Difference (A Intersect B).

Where is inside?

Before I go any further, I need to define what it means for a point or path to be “inside” of another. The previous examples were simple and just by eyeing them I could tell if a point or path section was inside or not. However, I’ll need something more robust for more complex operations.

Traditionally there are two ways to determine if a given point is inside a closed path or not. First, there’s the winding rule. I count how many times the path winds around the given point. If it’s more than 0, then the point is inside the path. This is default way NSBezierPath determines if a point is inside a path or not.

The second way is the even odd rule, which is the one I use in my implementation and for the rest of this post. I draw a ray from the given point to outside the bounds of the path. I then count how many times the ray intersects the path. If it is an odd number of times, then the point is inside the path. If even, it’s outside.

The star in the above diagram is one closed path. I’ve added three points A, B, and C to various places in the diagram, and applied the even odd rule to determine if they’re inside the star or not. The red arrow represents the ray I drew from the point to the outside of the path. (It doesn’t have to be a horizontal ray, it can go in any direction.) The ray from point A crosses the path exactly once, an odd number of times meaning it falls inside the star. The ray from point C crosses the path twice (even) so it is outside the star. Just by looking at the diagram it’s easy to see that A is inside and C is outside.

However, when I cast a ray from point B it also intersects with the star an even number of times, meaning it lies outside the path. This isn’t necessarily intuitive by looking at the diagram, but it is important for allowing holes in a path.

Both the winding rule and the even odd rule are called fill rules, because their main purpose is to determine which parts of a path are filled. Using the even odd rule the star above would be filled like:

The star has a hole in the middle. However, this isn’t the only way holes can be introduced to a path. Holes can be formed by unconnected subpaths. For example:

Here both the rectangle and ellipse are part of the same path; they’re just disjoint subpaths. As with the star, the same even odd rule applies meaning point A is inside the path, but B is not. The rectangle would be filled, except for the area the ellipse defines.

Nonintersecting Paths

Now that I’m done with that detour into fill rules and holes, I want to get back to boolean operations between two paths. I started with how to compute the results of a boolean operation if the two paths intersect, but what if the paths don’t intersect? There are two non-intersecting states I care about: when one path contains the other, and when the two paths lie outside of each other. I’ll start with two examples illustrating both of these states:

Contained
Disjoint

For the union operation, I want to eliminate any paths that are contained by another path. However a path is only contained by another if it falls inside the filled region as defined by the even odd rule. If the two paths lie outside of each other, the result of a union is both of them. So union-ing my two examples would result in:

Contained
Disjoint

Intersect, being the logical and, eliminates any area where both paths aren’t filled. In the case where one path contains another, the contained path is the one where both paths are filled. If the two paths don’t overlap in any way, then the result is nil.

Contained
Disjoint	(nil)

Difference starts with one path, which I’ll call A, and removes all the places that another path, B, fills. In the case of containment which path contains the other matters. If I’m computing A – B, and A contains B, then I’ll add B as a hole subpath to path A. If B contains A, then all of A subtracted away, and I’m left with nil. If the paths don’t overlap, and I’m computing A – B, then nothing changes and I’m left with A as the result.

For this example, assume the blue rectangle is A and the red ellipse is B.

Contained (A – B)
Contained (B – A)	(nil)
Disjoint (A – B)
Disjoint (B – A)

Intersecting Holes

Now that I’ve discovered holes, it’s time to see what happens when a path intersects with one. The process is the same as performing the operations on two normal paths, except which section (inside or outside) I chose to go in the result. I’ll start with a simple example:

In the above diagram, the blue rectangle and ellipse form one path, with the ellipse being a hole. The red circle forms the second path. As before the inside sections of the intersecting (sub)paths are shown in a dashed style.

For a union I’d normally choose the outside sections of both paths. However since the blue ellipse is a hole, the red circle should intrude into it. So I would pick the inside of the red circle and the outside of the blue ellipse. More generally, I would always pick the outside section of a path, unless the other path was a hole, then I’d pick the inside section. The union result would be:

Note that since the blue rectangle is nonintersecting, it passes straight through to the result. (See the previous section about nonintersecting paths.)

Intersect would normally choose the inside sections of each path. However, both paths clearly don’t exist inside of a hole. So when I choose which section to output for a given path, if the other path is a hole I’ll pick the outside section instead of the usual inside section. Here are the results of the intersect on these two paths:

In the intersect I remove the blue rectangle entirely, since it is a nonintersecting (sub)path.

In a difference operation the order of the operands matters, so I’ll take each direction separately. If I subtract the red (path B) from the blue (path A), normally I would chose the outside of A and the inside of B. However, just from eyeballing the paths I can tell that I should take the outside of B. When choosing which section to output for B, I look to see if A is a hole. If it is, I take the outside of B instead the inside, resulting in:

To compute B – A, I would usually pick the outside of B and the inside of A. But since A is a hole, I choose the inside of B, with the following results:

By now I’ve noticed a pattern for all the boolean operations. I choose the section of a path I normally would for that operation, unless the intersecting path is a hole. If it is I pick the opposite section than I normally would.

Exclusive Or Revisited

Now that I know about holes and how to perform union, intersect and difference on non-intersecting paths I can tackle exclusive or. I’ll return to the first example:

Now I take both the union and the intersect of both these paths, then subtract the intersect from the union for the final result. Below is the intermediate step after the union and intersect have been computed, but before the difference.

The union is in blue, and the intersect is in red. This diagram is a good illustration of an edge case. Technically there are two intersections between these two paths where the original rectangle and ellipse meet. However the two paths don’t fully cross each other at these intersections, they just meet at a point. Because of this, I ignore them. This holds true for any intersection: if the paths don’t cross each other then I ignore it for the purposes of boolean operations.

Since there are no crossing intersections, taking the difference happens between two paths that don’t intersect, and I fall back to those rules. The result of the xor:

There are two subpaths in the result: the union and the intersect subpaths. The interior subpath from the intersect thus forms a hole. If the result were filled, it would be:

Conclusion

All these pieces come together to be able to handle boolean operations for complex paths. First I handle all the intersecting subpaths as described, whether they are fill or hole. Then I process all nonintersecting subpaths, ignoring any intersecting subpaths for those computations.

This time I focused strictly on how to perform the boolean operations conceptually, based on the assumption I could find all the intersections. I covered how to think about paths as inside and outside sections, and how to perform boolean operations based on picking the correct section from each path. This is an important foundation for next time, when I’ll dig into the algorithms that actually implement these boolean operations.

Operation	Example
(None)
Union (Logical Or)
Intersect (Logical And)
Difference
Join (Exclusive Or)

Implementing them is somewhat involved, so I’m breaking the explanation up into two articles. This post will focus on finding intersections between individual bezier curves, and the next will show how to implement the boolean operations based on that. The algorithm presented will be able to handle arbitrary closed bezier paths, including those with holes and self intersections.

If you’re impatient, you can skip straight to the commented source code. As usual, I’ve released it under the MIT license. I encourage you to play with the sample application to see what it can do.

Clipping until it converges

This post I’m focusing on finding intersections between individual bezier curves using an algorithm called bezier clipping. It’s described in the paper “Curve intersection using Bezier clipping” by TW Sederberg and T Nishita. If you’re following along in the source code, it’s implemented in the FBBezierCurve class.

The first thing to realize is that finding intersections between curves isn’t exact. I won’t be able to plug the inputs into a formula and get back all the points where the curves intersect. Instead, I’ll iteratively whittle down the curves to ranges that could possibly intersect until I get down to a point or eliminate the curve entirely.

So the pseudocode for the main loop would be:

FBBezierCurve *us = ...; // passed in
FBBezierCurve *them = ...; // passed in
FBRange usRange = FBRangeMake(0, 1);
FBRange themRange = FBRangeMake(0, 1);
while ( !FBRangeHasConverged(usRange) && !FBRangeHasConverged(themRange) ) {
	BOOL intersects = NO;
	us = [us bezierClipWithBezierCurve:them range:&usRange intersects:&intersects];
	if ( !intersects )
		return; // no intersections
	them = [them bezierClipWithBezierCurve:us range:&themRange intersects:&intersects];
	if ( !intersects )
		return; // no intersections
}

Here a FBBezierCurve is one cubic bezier curve, as defined by two end points and two control points. FBRange is a parameter range defined by a minimum and maximum. A parameter value falls between [0..1] and is used for the parametric form of a bezier curve. In my case it keeps track of the range of the curve that could possibly intersect with the other curve.

The method bezierClipWithBezierCurve: refines the range passed in by determining the range where self could intersect with the curve passed in. It can also determine if there is no range where the two curves intersect. Don’t worry about how this is done right now, I’ll explain it later.

Each time through the loop I clip each curve a bit more, refining the range where the two curves might possibly intersect. The refined range is fed into the next iteration of the loop, which refines it a bit more. This continues until the minimum and maximum values of the range are close enough to be satisfactory (in my implementation, six decimal places). It’s also possible I discover, in clipping one curve against the other, that they don’t intersect at all. In that case, I can stop there.

The pseudocode above handles the common case where there is one (or no) intersection between the two curves. However cubic bezier curves can intersect up to nine times, so I need a way to detect when there are multiple intersections, and a way to find them. Detecting the possibility is easy; each time through the loop I compute how much I’ve reduced the intersection ranges by. If it’s less than 20%, then it’s likely there are multiple intersections, which would prevent the range from converging quickly.

Once I detect that I might have multiple intersections, I look at which range (and thus curve) is bigger. I split the correspond curve in half. I then recurse: for each of the halves I find the intersections between it and the other full curve. I take the combined results and return.

If you want to see the main loop in all it’s excruciating detail, check out the commented intersectionsWithBezierCurve:usRange:themRange:originalUs:originalThem: method. There are some implementation details I didn’t cover here, but are explained in the comments.

Fat Lines

In the previous section I glossed over how I can refine the range of a curve that could possibly intersect with the other curve. I’ll tackle how to do that now.

What I really need is a way to more simply represent the area a given bezier curve could possibly inhabit. Once I have that I can determine which parts of the other bezier lie inside of that area (and thus possibly intersect), and which don’t.

To this end, Sederberg and Nishita introduce the concept of a fat line. A fat line is a line through the end points of the bezier curve, but fat enough it encloses the entire curve.

Above you can see the bezier curve in blue and the fat line in the pink color, crossing through the curve’s end points. In code, the fat line is represented by a line (the dashed line above), plus two signed distances describing how far to extend the fat line above and below the dashed line. (Signed distance just means the value is negative if it falls below the line, positive if above.) The two distances form the bounds of the fat line, and are called the minimum and maximum bounds.

Computing an approximation to the minimum and maximum bounds is straightforward if I take advantage of the convex hull property. The convex hull is the polygon formed by connecting the end and control points with line segments. The convex hull property states that the polygon will completely enclose the bezier curve, as you can see below. The curve is in blue and the convex hull in red.

So to compute the minimum and maximum bounds, I just compute the signed distances of the end and control points from the dashed line and chose the minimum and maximum distances.

As you can see, using the convex hull to compute the minimum and maximum bounds doesn’t produce optimal results (i.e. the fat line fits loosely around the curve, not tightly). However the approximate bounds are cheap to compute and are good enough for my purposes.

Based on the fat line, it’s easy to see if any given point could possibly intersect with the bezier curve. Simply compute the signed distance from the line to the point. If that signed distance lies inside the fat line bounds, then it could intersect. If not, then it definitely doesn’t intersect.

Bezier clipping

I’ve simplified the clipping curve to a fat line and bounds, and can use it to see if a point could lie inside the clipping curve. Next I need to clip the subject bezier curve with the fat line.

The above diagram shows a range on the subject bezier that falls inside of the fat line, and thus could intersect with the other bezier. The piece inside the fat line is the bezier curve I want to end up with.

I start by calculating the signed distances of the end and control points of the subject bezier to the fat line. Next I construct a bezier curve from these distances, like so:

NSPoint endPoint1 = NSMakePoint(0, distance(fatline, subjectCurve.endPoint1));
NSPoint controlPoint1 = NSMakePoint(1.0/3.0, distance(fatline, subjectCurve.controlPoint1));
NSPoint controlPoint2 = NSMakePoint(2.0/3.0, distance(fatline, subjectCurve.controlPoint2));
NSPoint endPoint2 = NSMakePoint(1, distance(fatline, subjectCurve.endPoint2));

I spread the distance bezier points out evenly between 0.0 and 1.0 on the X axis, and use the distances from the fat line as Y values. By uniformly spreading the X values out, they will correspond to parameter values for the parametric form of the subject bezier.

Since the Y axis is the distance from the fat line, I can just throw the fat line bounds on the graph.

If I can calculate the X values of where the distance bezier crosses the minimum and maximum bounds, then I’ll have the range of the subject bezier that falls inside the fat line. To do that, I’ll once again rely on the convex hull property.

In the above diagram, the convex hull is the dashed red line. Computing the intersection of two lines is easy, so I find the intersections of the convex hull with the horizontal minimum and maximum lines. The lowest and highest X values define the parameter range on the subject bezier curve that fall into the fat line bounds, and thus could intersect the other curve.

There are two special cases here, both occurring when the distance bezier doesn’t intersect with the minimum or maximum fat line bounds. If the distance bezier falls completely inside the fat line bounds, then I can’t whittle the subject bezier down any, and I’m forced to return the entire subject bezier untouched. If the distance bezier lies completely outside the fat line bounds, I know the two curves don’t intersect, and return that.

If I did successfully refine the possible intersecting range, I need to cut down the subject curve to match. Fortunately, de Casteljau’s algorithm makes it easy to split bezier curves at a specific parameter value. See the BezierWithPoints() helper function for the implementation of that algorithm.

That completes how to clip one bezier curve against another. To summarize: compute a fat line and bounds from the clipping bezier, compute a distance bezier from the other curve, and see where the distance bezier’s convex hull intersects the fat line bounds. Using the intersections’ x values as the parameter range where the curves could intersect, cut the subject bezier down to match the range.

Points of interest

Although the above description presents the complete algorithm for finding intersections between two bezier curves, I wanted to point out a couple of other things. These are implementations details that I either found interesting and/or difficult.

1. After the main intersection loop (in intersectionsWithBezierCurve:usRange:themRange:originalUs:originalThem:) there’s a bit of code that checks to see if both curves have converged to a point. The loop bails as soon as one curve converges since the math for clipping falls apart as soon as one curve becomes a point. However for implementing the boolean operations, I need good parameter values for both curves. Since I know the 2D intersection point from the curve that converged, and I can guess a reasonable parameter value for the curve that didn’t, I can use Newton’s method to refine the parameter value of the curve that didn’t converge. Fortunately, that’s something I’ve done before when fitting curves to points.

2. In the method that clips one bezier curve against the other (bezierClipWithBezierCurve:original:rangeOfOriginal:intersects:) you’ll notice that I don’t compute and clip against one fat line, but two. The second fat line is perpendicular to the regular one:

   

   Most of the time the regular fat line will clip out more of the curve than the perpendicular one. However, clipping against the perpendicular fat line does help the possible intersection range converge more quickly.

3. I mention the convex hull a couple of times, but gloss over how to build it. It is made up of just the end and control points, but the order is important, and sometimes points need to be removed if they’re collinear. There are several algorithms to build the convex hull, but Graham Scan is supposedly the best for 2D curves. It took me a few tries to get it right. Not all of the reference implementations/descriptions that I found covered the edges cases, such as what to do when I encountered collinear points. The best I found ended up being this one.

   Check out the convexHull method for my implementation.

Conclusion

Although I’m finding bezier curve intersections for the purpose of performing boolean operations, it can be used for other applications as well. Heck if I know what those are though. So next time I’ll dive into implementing union, intersect, difference, and join.

Be sure to enjoy the complimentary source code in the mean time.

If you’re impatient, you can always skip to the source code. It is licensed under the MIT license.

Naive Implementation

The direct way to implement the vector brush would be to simply record the mouse movements into a NSBezierPath. On a mouse down, create an NSBezierPath, do a move to the first point, then on subsequent mouse drags add line to’s to the NSBezierPath. Since I already have an NSBezierPath now, I can just draw it to represent the brush stroke. If you run the sample application with all the options under the Options menu (Show Points, Simplify Path, and Fit Curve) turned off, it’ll do exactly that. A brush stroke will look something like:

That actually doesn’t look bad. Does that mean I’m done? To answer myself, I’ll turn on the Show Points option under the Options menu:

Show Points draws an orange, hollow square around each of the points that make up the path. As you can see, there are a ton of them, about 160 in this case. Having that many points means editing the path afterwards is going to be rather difficult. Also, I can see that most of the points are redundant; they aren’t adding any new information to the path.

Brush strokes, simplified

At this point the best way to improve the my brush is to remove all the redundant points from our NSBezierPath. Since all the extra points don’t get in my way until mouse up happens, I’ll simply do some post processing on the NSBezierPath on mouse up. I’ll use the Ramer-Douglas-Peucker algorithm to identify and remove the redundant points. To demonstrate the effects of this algorithm, I’ll turn on the Simplify Path option, and draw another brush stroke:

You can see a big difference here in the number of points required to make up the path. The sample application outputs (using NSLog) how many points the path had before and after simplifying the path. In this case, the points went down from 170 to 15.

The Idea

The idea behind the Ramer-Douglas-Peucker algorithm is pretty simple. It takes a path and a threshold as parameters. I’ll show an example to demonstrate it. Let’s start with the following path:

I’ve numbered the points for easy reference. To start with I imagine a line between the end points, 1 and 5. I then measure the distance between each of the interior points (2, 3, 5) and the line made by points 1 and 5.

I take the greatest distance (the one between point 3 and my line) and compare it to the threshold passed in. If the distance exceeds the threshold, I have to subdivide the path and recurse. I split the path at the greatest distance (point 3 in this case), which gives me two paths: [1, 2, 3] and [3, 4, 5].

I repeat the process on [1, 2, 3] as my path:

Here my end points are 1 and 3, and my only interior point is 2. Like before I take the distance between point 2 and the line formed by 1 and 3, and compare it to the threshold passed in. In this case, the distance is less than threshold. Thus, I can say the interior points are all redundant and the path [1, 2, 3] can be represented by the endpoints 1 and 3.

Going back to the second recursion mentioned, I repeat the same process on [3, 4, 5]. In this case the distance between point 4 and the line between points 3 and 5 is less than the threshold. Because of that, I can represent the path [3, 4, 5] with just the end points 3 and 5. Thus, the final result is:

The Code

As you might expect the code for this algorithm is rather simple. It’s just one method (not counting the utility methods to access NSBezierPath data), which I’ve added as a category to NSBezierPath.

It takes a threshold as a parameter and returns the simplified path. It needs at least three points on the path before the algorithm will work.

- (NSBezierPath *) fb_simplify:(CGFloat)threshold
{
    if ( [self elementCount] <= 2 )
        return self;

Next it calculates the distance between the interior points and the line formed by the two end points. It remembers the largest distance and where in the path that point is.

    CGFloat maximumDistance = 0.0;
    NSUInteger maximumIndex = 0;

    // Find the point the furtherest away
    for (NSUInteger i = 1; i < ([self elementCount] - 1); i++) {
        CGFloat distance = FBDistancePointToLine([self fb_pointAtIndex:i], [self fb_pointAtIndex:0], [self fb_pointAtIndex:[self elementCount] - 1]);
        if ( distance > maximumDistance ) {
            maximumDistance = distance;
            maximumIndex = i;
        }
    }

FBDistancePointToLine() is a function I wrote that calculates the distance between a point and a line. fb_pointAtIndex is just a helper method that returns the point on the path at that index.

Now that it has the greatest distance, it checks to see if that distance is significant. If it is, then it recurses on itself, passing in the two halves split by the greatest distance. When the recursive calls return it joins the two results back into one, and returns those.

    if ( maximumDistance >= threshold ) {
        // The distance is too great to simplify, so recurse
        NSBezierPath *results1 = [[self fb_subpathWithRange:NSMakeRange(0, maximumIndex + 1)] fb_simplify:threshold];
        NSBezierPath *results2 = [[self fb_subpathWithRange:NSMakeRange(maximumIndex, [self elementCount] - maximumIndex)] fb_simplify:threshold];

        [results1 fb_appendPath:[results2 fb_subpathWithRange:NSMakeRange(1, [results2 elementCount] - 1)]];
        return results1;
    }

fb_subpathWithRange: is another utility method. It makes a copy of part of the path specified, and returns it. fb_appendPath appends one path to another, except it also will remove spurious move to’s and replace them with line to’s.

Finally, if the greatest distance isn’t significant, then all the interior points are redundant. In this case, just create a new path with the two end points.

    NSBezierPath *path = [NSBezierPath bezierPath];
    [path fb_copyAttributesFrom:self];
    [path moveToPoint:[self fb_pointAtIndex:0]];
    [path lineToPoint:[self fb_pointAtIndex:[self elementCount] - 1]];
    return path;
}

The only new utility method this time is fb_copyAttributesFrom:, which copies over attributes like caps, joins, and miters to the target path.

Curvy is better

So now I have a much simplified path representing my brush stroke. But my path is comprised of lines only, which are quite limited in representing anything other than a line. I’d like to have a way to represent curves. That way editing the path afterward would be even more powerful, plus I could reduce the number of total points on my path even more. Enter bezier curves.

Defining bezier curves is beyond the scope of this article. As far as this post is concerned they are a parametric curve defined by four points: two end points and two control points.

To further improve my brush stroke, I’m going to take my simplified path of lines, and fit a series of bezier curves to it. The algorithm for doing this is documented in Graphics Gems 1 in the article titled “An Algorithm for Automatically Fitting Digitized Curves” by Philip J. Schneider. Unfortunately, Graphics Gems is out of print. A Kindle version is available on Amazon, but it is 1) US$80 and 2) a poor quality scan. I would suggest buying the book used if you want a copy.

You can see the results of curve fitting by turning on the Fit Curve options in the Options menu and drawing a stroke. Here’s an example:

The black boxes are bezier curve control points. In this case using both path simplification and curve fitting reduced the number points from 197 to 7. Even better, bezier curves give the user more flexibility and power when it comes to editing the path.

Curve fitting overview

The curve fitting technique is somewhat involved and makes use of several different algorithms. I’ll only cover the methods unique to the algorithm and skip over a lot of details. That said, the sample code is complete and commented, so it can be used to fill in the details.

To start with, I’ll assume the function Q(t) represents a bezier curve that fits the points on my path. The parameter, t, ranges from 0 to 1, and Q(t) outputs x,y coordinates on my bezier curve. The first thing to do is calculate estimated values of t that match up to the points on my path. That is, Q(t[index]) should equal the point on my path at index.

After generating inputs for Q(t), the next step is to try to fit one bezier curve to the all the points on the path given the inputs. (I’ll describe the exact process later.) I’ll then compute how far the resulting bezier curve falls from the points on my path. If the curve is close enough, then I’m done.

If the bezier curve isn’t close enough to fit, I’ll see if it’s close enough that it makes sense to refine the inputs (t). If it is, I’ll repeatedly refine the input parameters (t) using Newton’s Method, until the resulting bezier curve fits sufficiently or I try more than four times.

If refining the input parameters doesn’t lead to a fit, it’s time to give up on one bezier curve, divide the path, and recurse. I’ll split the path into two at the point the bezier curve is furtherest from (i.e. where the greatest error is at). I’ll then recurse on the two halves, and then combine the two resulting curves into one bezier path for the final result.

The method fb_fitCubicToRange: in the NSBezierPath (FitCurve) category contains the code for the process described above if you want more detail.

Fitting a bezier curve to points

Remember that a bezier curve is defined by four points, like below.

Here points 1 and 4 are the end points and 2 and 3 are the control points. The orange lines just visually connect the control point with its corresponding end point. The blue curve is the bezier itself.

If we’re given a path of points to fit a curve to:

it’s easy to select the end points of the bezier curve; they’re simply the end points of the path (1 and 6 here). The direction of the control points relative to their end points is also simple to determine: simply compute the vector between the path end points and their nearest neighbor. In this case the direction of the left control point is the vector between points 1 and 2 in the path. The right control point direction is the vector between points 5 and 6. The only unknown in constructing our bezier curve is the distance between the control points and their respective end point.

Stated another way:

leftEndPoint = first point in path
rightEndPoint = last point in path
leftControlPoint = leftAlpha * leftTangent + leftEndPoint
rightControlPoint = rightAlpha * rightTangent + rightEndPoint

Where leftAlpha is the distance between the leftEndPoint and leftControlPoint, and rightAlpha is the distance between the rightEndPoint and the rightControlPoint. leftTangent and rightTangent are the unit vectors between the end points of the path and their closest neighbors.

By controlling the distance of the control points from their end points, I can affect the curve of the bezier. I want to chose distances (leftAlpha and rightAlpha) such that it best fits the points in the path. Formally stated, I want to minimize the squared errors as represented by:

S = SUM( (point[i] - Q(t[i])) ^ 2 )

Where point[i] is the point on the path at index i, t[i] is one of the estimated parameters I generated earlier, and Q is bezier curve. Remember that point[i] should be equal to Q(t[i]), assuming the bezier curve fits perfectly my points. Here I’m calculating how far each point on the bezier curve is off, squaring that, then adding it all up (squared errors). This is the error I calculate when I’m trying to determine if a bezier curve is close enough that I’m done. Right now though, I want to minimize S when calculating leftAlpha and rightAlpha.

Using the least squares approach I can write the equations I want to solve as:

d(S) / d(leftAlpha) = 0
d(S) / d(rightAlpha) = 0

Here d() is derivative, usually written as the Greek letter delta. S is the squared errors defined above.

At this point I do need to introduce the definition of a bezier curve:

Q(t) = SUM(V[i] * Bernstein[i](t))

Where i ranges between [0..3], and V is one of the points on the bezier curve. V[0] is the leftEndPoint, V[1] the leftControlPoint, V[2] the rightControlPoint, and V[3] the rightEndPoint. Berstein[i] is a polynomial that is highly regarded as boring for this discussion. (Look at the code if you really want to know.)

Now that I have Q defined, I can substitute it in the equation S, and then S into the two equations I want to solve. After a lot of mathematical voodoo and gymnastics (see the paper for all of that), I arrive at:

leftAlpha = det(X * C2) / det(C1 * C2)
rightAlpha = det(C1 * X) / det(C1 * C2)

Here det() is determinant, * is the dot product, and X, C1, and C2 are all 2×1 matrices defined below.

C1 = [SUM(A1[i] * A1[i]), SUM(A1[i] * A2[i])]
C2 = [SUM(A1[i] * A2[i]), SUM(A2[i] * A2[i])]
X = [SUM(partOfX * A1[i]), SUM(partOfX * A2[i])]

Where

partOfX = (points[i] - (leftEndPoint * Bernstein0(t[i]) + leftEndPoint * Bernstein1(t[i]) + rightEndPoint * Bernstein2(t[i]) + rightEndPoint * Bernstein3(t[i])))

And

A1[i] = leftTangent * Bernstein1(t[i])
A2[i] = rightTangent * Bernstein2(t[i])

If you’re interested in how this all plays out in code, check out the method fb_fitBezierInRange: in the NSBezierPath (FitCurve) category.

Calculating parameters (i.e. t)

The parameters (t) are useful for correlating the points on my path with the bezier curve I’m trying to fit. I know that t has to range from 0 to 1, and Q(t) is supposed to correspond to the points on my path. Q(0) should be the first point on my path, and Q(1) should be the last.

The initial estimate of t uses the chord length method. Ideally, t would be the length of curve from the left end point to the point corresponding to t, divided by the total length of the curve. However, the chord length method makes the assumption that a straight line is a reasonable estimate of a curve. So to estimate t, I measure the length of the line segments from the left end point to the point corresponding to t, then divide that by the length of all the line segments.

You can inspect the implementation of this in the fb_estimateParametersUsingChordLengthMethodInRange: method.

If my initial estimate proves to be poor, I can further refine it using Newton’s Method. Newton’s Method says I can refine each t value by:

t = t - f(t) / f'(t)

In my case

f(t) = (Q(t) - point) * Q'(t) = 0

Here (Q(t) – point) is the vector from a point on the bezier curve to the corresponding point on my path. Q’(t) is the first derivative, which is tangent to the bezier curve, Q, at t. (Q(t) – point) is orthogonal to Q’(t), which means the dot product of the two is zero.

Based on that, f’(t) is

f'(t) = (Q(t) - point) * Q''(t) + Q'(t) * Q'(t)

The NewtonsMethod() function in NSBezierPath+FitCurve.m implements this.

Conclusion

Although I skipped over a lot of detail when it came to curve fitting, hopefully this post has been helpful in understanding how it works, in addition to explaining the vector brush. For the details that I skipped over, the code should fill in the blanks. The vector brush is a fun tool to play with and the curve fitting algorithm has other applications too.

Way back in 2008 the original iPhone SDK came out, and I, like a lot of people, was excited about developing apps for the iPhone. My company is primarily a software development services company so I was mainly interested in learning the SDK so we could pick up iPhone contracts in addition to Mac ones. It also happens to be the case that my favorite card game is hearts, so I decided a good way to learn the iPhone SDK was to write my own hearts game.

After a couple of weeks I had the basic functionality implemented, and noticed I was playing it a lot. I realized then that I could probably make this into a product. Furthermore, releasing an iPhone app through the App Store seemed like a good way for us as a company to begin making the transition from a services based company to a product based one.

If I was going to release Hearts Attack as a published app, I knew the UI and presentation had to be greatly improved. I went through a lot of mockups for the main playing view, including one where everyone’s cards — all 52 of them — were always visible somewhere on the table (a truly horrible idea). Unfortunately I don’t seem to have most of the mockups around anymore, but I found a couple which you can see below. (See the product page for the end result.)

The biggest challenge I had was fitting everything on the screen and it still being legible and usable. By trial and error I figured out how small I could make the cards and still make them tappable, as well as their optimal position to make them accessible with one hand.

I began thinking about what would make Hearts Attack unique or different from its competitors. Back then there were literally just two iPhone hearts games in the App Store, and I felt pretty confident that what I had was already better than them, but I wanted to be sure. I decided on: oddball talking computer opponents, a tutorial that gave not only card suggestions but the rationale behind the choice (a pet peeve of mine), and multiple undo support for mis-taps and tactical errors.

The last step was to get professionals to do the sound and graphics. I ended up hiring a sound designer, a graphics designer, and a character illustrator. The sound design went smoothly, but getting the graphics done was a lot more involved than I anticipated, which is another story for another day. Jordan of OneToad Design created the app icon, playing backgrounds, and the special card backgrounds for the queen of spades and jack of diamonds. Lara Kehler did the character illustrations, which turned out great.

Unfortunately, Hearts Attack went on hiatus in early 2009. I was working full time on an iPhone contract, and simply didn’t have a lot of time to put into Hearts. Secondly, I had lost all desire in finishing it. It was becoming increasingly apparent that iPhone users didn’t want to pay more than $0.99 for anything, despite all the whining I did about it. I convinced myself it wasn’t worth releasing Hearts because it would never make back the money it cost us to make. Hearts stayed dormant for an entire year.

A couple of months ago, I decided to pick Hearts Attack back up again. I had the time and, as someone pointed out to me, it would never make money if I didn’t release it. I was tempted to update the app to the latest SDK (I started Hearts back before you could even use nibs on the iPhone) and add some features. I decided against this, because I really just wanted to ship it. I did have to update it to the 2.2.1 SDK because the current Xcode tools no longer ship with the 2.0 SDK.

Instead I focused on fixing the bugs and adding polish. Fortunately for me my wife happens to be a professional software tester with iPhone experience, so I got lots of good bugs to fix. I also prepared a press release, created a website, and otherwise got ready for the release. After I felt the app was stable enough, I submitted it to Apple on Friday. It was approved on Monday.

At this point, I’m still not convinced I’ll ever make back the money we spent on sound and graphic designers. A hearts card game simply is never going to be a big seller, and price point isn’t high enough to make up for that. Right now, I’m tending to think pessimistically about sales, but I’m going to do what I can to drum up sales and see how things go.

It’s a “wait and see” situation as to if we develop any more iPhone applications to sell ourselves. Of course, regardless of how well Hearts Attack does, we’d be happy to develop your iPhone app for you.

But at the risk of having my programmer’s license revoked, I have to confess I don’t really care about version control systems. I mean, I think it’s important to use version control, but I don’t get all excited about the latest ideas in version control technology or the newest VCS on the block. It’s just a tool. It keeps versions of all my code, and allows me to revert to previous versions, see when and how things changed, and collaborate with other programmers working in the same codebase. Beyond that I don’t much care.

The tools don’t make the programmer.

What’s new with DVCS is the proponents seem to think they need to evangelize their system. Unfortunately they rather suck at it, and their arguments usually leave me feeling that I don’t want to use software used by such jerks, on account that it might make me into a jerk. Or at least a bigger one.

However, I do think that a DVCS can be a really useful tool so I’ve come up with some suggestions for those wanting to effectively evangelize their favorite version control system, or at least annoy me less when they talk.

1. Don’t be condescending or insulting

   I think it’s part of human nature — or at least programmer nature — to assume you’re the smartest guy in the room, and think that anyone who disagrees with you is a real buffon. Programmers seem to take great pleasure in showing that the other person is an idiot, or didn’t know something they did, or is at least not as clever as they are. A lot of arguments for git or Mercurial seem to revolve around explaining how git or Mercurial are so clearly superior that only morons would use something else.

   While this works great for rallying the troops, it’s counterproductive when trying to win someone over to your side.

   Think of it this way: suppose someone comes to your door to tell you about their religion. During the discussion they are self righteous and condescending; they don’t listen to your arguments, but are only interested in proving that they’re right. Are you likely to be swayed to believe in their religion? If you’re like the other hairless bipedal mammals inhabiting this planet you won’t be, even if they had some valid points.

   As soon as you become insulting or condescending, your arguments will be rejected out of hand. I know this will upset some programmers because they believe if you show your argument is superior, everyone will accept it. But that’s not the way people work.

2. Try to be helpful

   The best way to introduce someone to your DVCS is by trying to help them. Not in the “I have all the answers” way, but in the “I’ve dealt with that before, and here’s what I did” kind of way. People will run into the kinds of problems that DVCS are good at solving. When they do, you can helpfully suggest a solution.

   However, some care should be taken so the suggestion doesn’t come off the wrong way.

   Wrong	Right
   Dude, why are you using subversion?	I’ve run into that problem before. I solved it by using feature X of git/hg in this way.
   Dude, just use git/hg.	You smell nice.

   Be aware that people may not know where their pain points are. I’ve seen customers jump through some excruciating hoops to get a piece of software to do something when there was an easier way. People get used to pain and begin to assume it’s normal. If you notice something like that, even if they’re not complaining about it, you can politely suggest a better way.

   Instead of a list of features that a DVCS provides or abstract arguments as to why they should be using it, people respond better to concrete examples of how a piece of software can make their lives better. People are also more responsive when they know you’re on their side, trying to help them, even if they don’t — or currently can’t — take your suggestion. Keep in mind switching VCS in the middle of product cycle is likely something most people can’t do.

   The right attitude is that of trying to help a friend, not conquer an enemy.

3. Be willing to answer questions, even dumb ones

   Distributed version control works differently from centralized version control, and it does require a different way of thinking. I know I was confused by it when I first started looking into it. A lot of tutorials jump into the mechanics of how to perform certain tasks, but rarely talk about the philosophy of the system or why things are the way they are. If you want to successfully persuade people that your DVCS is the best then you need to be willing to do a lot of patient education.

   I say “patient” because after using centralized version control they might have difficulty switching over to a new mental model. Or they might have heard a lot of FUD about your DVCS that you need to put to rest. It’s important to do this patiently, respectfully, and not insultingly because they’ve picked up misinformation or don’t immediately “get it” like you do. Otherwise they might ignore your DVCS so they don’t have to deal with people who look down on them because they don’t “get it.”

4. Make it trivial to install and use

   This seems like a no brainer, but it is an important part of any software. If it’s hard to try out and use your DVCS, it simply won’t get used. I think that for the most part both git and Mercurial succeed in this respect. My only complaint is neither has a good Mac GUI client. Contrast that with Subversion which has both Versions and Cornerstone on the Mac. You shouldn’t underestimate the draw of an easy to use, beautiful GUI.

I think Joel Spolsky has given the best example of how to properly promote and evangelize a DVCS. He wrote a blog post — Distributed Version Control is here to stay, baby — about how he came to learn and use DVCS. It’s well written, and instead of condescending, he’s actually humble and admits he was wrong about DVCS to begin with. Joel also created a site called HgInit that does an amazing job of explaining the philosophy behind Mercurial and gives a solid introduction to right way to use it. It’s actually the site that convinced me to start using Mercurial for real.

Unfortunately, I’ve not had much luck with Quartz Composer in way of meaningful compiler errors. Sometimes it returns good errors, sometimes inscrutable ones.

Composer: Wait, wait, I remember this… it’s COBOL, right?

However, I’ve found debugging OpenCL kernels to be much easier thanks to the invention of a function I like to call “printf.” If you run your kernel on the CPU, then you can print out values just like in C. With debugging solved, I just needed to figure out how to find compiler errors without having to run my code.

Unlike Core Image, OpenCL actually requires you to compile your kernel code explicitly before using it. The API’s required to do this will return nice compiler error messages and everything. The obvious thing to do would be wrap up these API’s in a command line tool and invoke the tool from Xcode, which is what I did.

The Code

You can download the Xcode project for clc, the OpenCL Compiler here. It requires Mac OS X 10.6 Snow Leopard and the associated Xcode tools. To install, just build the project and copy the resulting binary into your path somewhere. I used ~/bin.

Most of the code is self explanatory, with the possible exception of the output. Unlike most compilers, clc doesn’t output object code because the host and runtime CPU/GPU’s could easily be different. It could simply copy the source code as is for the output, but that was a little too obvious for my tastes. Instead clc compresses the source code and stuffs it into a binary plist. It has the slight benefit of potentially being smaller on disk, and making your source code negligibly less accessible to prying eyes, if you’re into that sort of thing.

There are definite possibilities for improvement. For example, there could be an option to encrypt the source code to be more “secure.” Or it could store the binary code generated by the host machine in the output on the chance that the host and runtime machines have the same hardware.

Setting up Xcode

To use clc, you’ll need to set up a build rule in your app’s target settings to run all OpenCL source files through it. Selecting the menu item Project > Edit Active Target, and then selecting the Rules tab, should land you here:

Add another rule, set it to process OpenCL source files using a Custom script. For the custom script enter:

~/bin/clc ${INPUT_FILE_PATH} -o ${TARGET_BUILD_DIR}/${PRODUCT_NAME}.app/Contents/Resources/${INPUT_FILE_BASE}.clar

Finally, you’ll need to tell Xcode where you’re putting the output file, which is:

${TARGET_BUILD_DIR}/${PRODUCT_NAME}.app/Contents/Resources/${INPUT_FILE_BASE}.clar

By default, Xcode won’t put OpenCL source files (.cl) into the target, meaning they won’t get compiled. For each of your OpenCL source files
you’ll need to explicitly add them to your target. There are several ways to do this, but the easiest is probably selecting all of them, and doing a Get Info (File > Get Info). Switch to the Targets tab and check the target they should be compiled into.

Runtime Code

At runtime, it’s pretty easy to retrieve the original OpenCL source code using the + (NSString *) openCLSourceWithData:(NSData *)data error:(NSError **)error; method on ONOpenCLArchive. However, there are a couple of convenience methods on NSBundle that makes retrieving the kernel easier. For example:

#import "ONOpenCLArchive.h"

NSString *kernelSource = [[NSBundle mainBundle] openCLResource:@"MyKernel"];

That’s pretty much all there is to it.

Conclusion

Although not ground breaking, this little tool has certainly been helpful to me by finding compiler errors at compile time instead of runtime. Hopefully it will be useful to other people as well.

This year they aren’t content with bringing conference justice to only the UK, so they’re branching out to the good ‘ole U.S. of A. by way of Atlanta, GA. To help you decide which conference you should attend, US or Europe, I’ve prepared the following quiz:

1. What is your opinion of Seattle?

   1. It’s nice, but isn’t nearly rainy or dreary enough.
   2. I like their coffee.
   3. The residents have too many teeth.

2. Describe your driving habits

   1. I like to drive on the left side of the road.
   2. I like to drive on both sides of the road.
   3. I like to merge right six lanes without signaling while going 147 mph on the off ramp and giving the finger with both hands in my black Camaro.

3. The pinnacle of human achievement is…

   1. Afternoon tea
   2. Sliced bread
   3. Hee Haw

Scoring: Give yourself -1 points for any 1 answer, 0 points for any 2 answer, and 1 point for any 3 answer.

If you scored is less than zero, you should attend NSConference Europe; if greater than zero, NSConference USA. If you scored exactly zero, you are truly a cultured individual and should attend both.

Personally, I’ll be attending both, and not just because of peer pressure and insightful quizzes. I’ll be presenting a talk on how to implement a watercolor brush using Core Image and OpenCL and maybe some duct tape. If you enjoy the graphics articles that I post here, you’ll probably enjoy my presentation. If not, I hear Steve “I’m Batman” Scott does a mean Adam West impression.

However, one of my frustrations with working with other app’s AppleScript interfaces was trying to figure out how the interface was intended to be used. Sure, the AppleScript Editor would show me all the actions and classes, but it isn’t always obvious how things are supposed to fit together. Something that would help in these cases is AppleScript recording. I could record the app performing the actions I cared about, then examine how the app itself used the actions and classes. Unfortunately, it seems like only the Finder and BBEdit ever got around to implementing AppleScript recording.

In the hopes of increasing the number of apps with AppleScript recordability, I’m going to document my approach to implementing it. For brevity, I’ll assume you’ve already an AppleScript interface implemented for your Cocoa app.

Thinking Big Design Thoughts

If you have an AppleScript interface for your application, you may think of your app architecture as something like this:

Here your AppleScript interface and graphical interface are independent peers, and both modify your model classes directly to accomplish your application’s tasks. Each interface is separate and largely ignorant of the other.

However, when implementing AppleScript recordability it is helpful to think about your app’s architecture in a different way:

In this case the GUI is dependent on, and implemented in terms of, the AppleScript interface. The general guideline is that anything the GUI does that mutates or alters the model goes through the AppleScript interface. However, if the GUI simply needs to access or get information from the model, it would go directly to the model, not through the AppleScript interface. Accessing the model can happen at seemingly random times to the user, and spamming the AppleScript Editor with these accesses when recording only confuses the user.

Suppose an application has table view and a button that deletes the currently selected item in that table view. The table view data source would be implemented the standard way, simply going directly to the model, bypassing the AppleScript layer. However, the delete button, since it alters the model, would be implemented by invoking the AppleScript delete command on the object represented by the current table row.

This design has some other benefits besides recordability. Notably it helps test your AppleScript interface design and implementation. If you find that implementing a GUI feature in terms of your AppleScript interface is impossible or difficult, congratulations, you found a bug! Also, merely testing your GUI also exercises your AppleScript interface. It is not a replacement for testing your AppleScript interface explicitly, but it certainly helps.

Implementation Hardships

Everything I’ve talked about so far hasn’t been all that novel, and probably has been met with large bucket fulls of “well, duh”s by anyone who’s ever looked into implementing AppleScript recording. The problem isn’t thinking about how to design in recordability, but actually implementing recordability.

As things stand now, doing something as simple as “invoking the AppleScript delete command on the object represented by the current table row” is incredibly involved and painful. You have to manually build up the AppleEvent that represents the delete command and the target model object using functions like AEBuildAppleEvent or classes like NSAppleEventDescriptor. Then you have to remember to target your app by specifying the kCurrentProcess process serial number (specifying kCurrentProcess as the ProcessSerialNumber is currently the only way to enable recording. Bundle identifiers, urls, and pid_t’s do not work.), and parse the AppleEvent you get back into something useful. You’d have to do this for every property or method on your model object you want exposed for recordability.

Dreaming of Ponies

The thing is, the Cocoa runtime has a lot of the AppleScript information from your SDEF file at its disposal and could theoretically generate these interfaces for you. In the ideal hypothetical situation, invoking the delete action via AppleScript inside your app could be as simple as:

// Suppose ONEmployee is our model object, with the appropriate AppleScript interface implemented
ONEmployee *employee = [_employees objectAtIndex:0];
ONEmployeeASProxy *proxy = employee.appleScriptInterface;
[proxy delete];

Here, any object that implemented the objectSpecifier method for AppleScript support would automatically get an appleScriptInterface property. The object returned by appleScriptInterface would be a proxy object implementing the same methods and properties as the original object. The proxy object would implement these methods by building up the appropriate AppleEvents, sending them, and parsing the resulting event back into a usable object.

Apple actually gets tantalizingly close to this with the Scripting Bridge. Outside users of your app can run your SDEF file through the sdp command line tool and get a nice Objective-C interface of proxy objects that build, send, and parse AppleEvents to and from your app. However, there is not currently a way tell these proxy objects to target kCurrentProcess, or to initialize one of the proxy objects by passing in a model object that implements objectSpecifier. (I’ve written this up as rdar://problem/7359646.)

Harsh Reality

Since I didn’t want to wait on Apple to extend the Scripting Bridge to make my life easier, I decided to write a couple of classes to help out. You can download the code here. The code is under the MIT license.

The classes work similar to the SBObject and SBElementArray classes in the Scripting Bridge framework. Using these classes, you can invoke the delete AppleScript method like so:

// Suppose ONEmployee is our model object, with the appropriate AppleScript interface implemented
ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) invokeCommand:@"delete"];

The ASObj function creates an ASObject proxy object for any NSObject that implements objectSpecifier. invokeCommand takes care of marshalling the parameters into an AppleEvent, sending it, and unmarshalling the return value into an NSObject. The name of the command is the name of the name used in AppleScript, not the Cocoa implementation.

invokeCommand can take parameters, although it gets more tricky:

ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) invokeCommand:@"giveRaise" with:[NSNumber numberWithInt:10], @"Percent", nil];

First, the parameters must be named (it’s not done by parameter order), and those names must match the Cocoa Key in the SDEF, not the user visible parameter name. Second, the marshalling code (from random NSObjects to AppleEvents) is a bit sparse. I’ve only added code for the types I needed for my project. If you use it, you may need to add support for other types. The same goes for return values; I only added support for the types that I use.

ASObject also has support for properties. For example this marks an employee as exempt:

ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) setObject:[NSNumber numberWithBool:YES] forProperty:@"isExempt"];

The same type restrictions for parameters apply to properties as well. The Cocoa Key for the property must be used here, the same as parameters.

Elements also have basic support, which is where the ASElementArray comes in. Right now the only interesting thing to do with an element array is retrieve a reference to a specific element:

ONEmployee *employee = [_employees objectAtIndex:0];
ASObject *dependent = [[ASObj(employee) elementForKey:@"dependents"] objectAtIndex:0];
[dependent setObject:[NSNumber numberWithBool:YES] forProperty:@"insured"];

Unlike other methods, ASElementArray‘s objectAtIndex does not execute an AppleEvents or otherwise take any actions. Instead it constructs an object specifier (i.e. an ASObject) for the given element.

The code is still somewhat rough and incomplete, but should help with anyone wanting to implement AppleScript recording. If nothing else, it should serve as a starting point or sample code for anyone rolling their own solution.

The sharpen tool has the following effect on this tweed pattern:

Notice the stripe through the middle where the edges are more strongly defined.

The blur tool has the opposite effect of sharpen on the tweed pattern:

Implementation Overview

Like the sponge tool, the sharpen and blur tools are subclasses of the FilterBrush class introduced in the dodge and burn tutorial. However, unlike sponge, they do require a slight modification to the GenericBrush class to work.

Since almost all of the code in this tutorial has been covered before, I’ll just highlight the single change to the GenericBrush class, and the new Sharpen and Blur classes. If you want to see everything, download the code.

Changing GenericBrush

If you recall, at the very beginning of this article I mentioned that sharpen and blur tools typically allow the user to modify the blend mode. This is the blend mode used when stamping the filtered image back on to the original image. GenericBrush contains the code that handles the stamping, so it will need to be modified.

We change the render:at: method for GenericBrush to be:

- (void) render:(Canvas *)canvas at:(NSPoint)point
{
	CGContextRef canvasContext = [canvas context];
	CGContextSaveGState(canvasContext);

	CGPoint bottomLeft = CGPointMake( point.x - CGImageGetWidth(mMask) * 0.5, point.y - CGImageGetHeight(mMask) * 0.5 );

	// Our brush has a shape and soft edges. These are replicated by using our
	//	brush tip as a mask to clip to. No matter what we render after this,
	//	it will be in the proper shape of our brush.
	CGRect brushBounds = CGRectMake(bottomLeft.x, bottomLeft.y, CGImageGetWidth(mMask), CGImageGetHeight(mMask));

	CGContextClipToMask(canvasContext, brushBounds, mMask);
	CGContextSetBlendMode(canvasContext, [self blendMode]);
	[self renderInCanvas:canvas bounds:brushBounds at:point];

	CGContextRestoreGState(canvasContext);
}

The only change made is the call to CGContextSetBlendMode that allows brush subclasses to determine the blend mode to use. The default implementation is simply:

- (CGBlendMode) blendMode
{
	return kCGBlendModeNormal;
}

That’s it for GenericBrush.

Sharpen Tool

The sharpen tool has just two parameters: mMode, which is the blend mode, and mStrength which determines how strong the sharpen effect is applied. They are initialized in init like so:

- (id) init
{
	self = [super init];
	if ( self != nil ) {
		// Set the default values for our parameters
		mMode = kCGBlendModeDarken;
		mStrength = 1.0;
	}
	return self;
}

Here are some examples of the sharpen tool parameters:

mMode	mStrength	Result
kCGBlendModeNormal	0.5
kCGBlendModeNormal	1.0
kCGBlendModeDarken	1.0
kCGBlendModeLighten	1.0

The blend modes typically offered for a sharpen tool are kCGBlendModeNormal, kCGBlendModeDarken, kCGBlendModeLighten, kCGBlendModeHue, kCGBlendModeSaturation, kCGBlendModeColor, and kCGBlendModeLuminosity. In the examples above, kCGBlendModeDarken causes the sharpening to only affect light pixels and kCGBlendModeLighten only affects dark pixels.

The heart of the sharpen tool is the filter it creates. The code for that is:

- (CIFilter *) filter
{
	// We need to create and configure our filter here
	CIFilter * filter = [CIFilter filterWithName:@"CIUnsharpMask"];
	[filter setDefaults];
	[filter setValue:[NSNumber numberWithFloat:mStrength * 100.0] forKey:@"inputRadius"];
	return filter;
}

You’ll notice that I’m using the unsharp mask filter to do the sharpening. I should point out that most image editors don’t use this filter to do the sharpening. Instead, they seem to use a convolution filter to do the sharpening. However, the convolution filter means it is easy for the user to overdue the effect. Unsharp mask does not have that problem, plus unsharp mask is provided by the system.

The final bit of the sharpen tool is returning the correct blend mode:

- (CGBlendMode) blendMode
{
	return mMode;
}

Blur Tool

The blur tool is very similar to the sharpen tool. It even takes the same parameters. The only real difference is the filter that it creates, so that’s what I’ll present first:

- (CIFilter *) filter
{
	// We need to create and configure our filter here.
	CIFilter * filter = [CIFilter filterWithName:@"CIBoxBlur"];
	[filter setDefaults];
	[filter setValue:[NSNumber numberWithFloat:mStrength * 7.0] forKey:@"inputRadius"];

	return filter;
}

Here I use the built in CIBoxBlur. mStrength ranges from 0 to 1, inclusive. I set the coefficient of 7 simply by trial and error until I got something that “looked right.”

Here are some examples of the blur tool:

mMode	mStrength	Result
kCGBlendModeNormal	0.5
kCGBlendModeNormal	1.0
kCGBlendModeDarken	1.0
kCGBlendModeLighten	1.0

Conclusion

Sharpen and blur are the last of the common filter brushes. Enjoy, and download the sample code.