Overview

Geometry Widget is an interactive shape input method, enabling users to draw 2D geometric constructions freehand, with a finger or a stylus. It is designed to ensure a natural, handwriting-based HMI with real-time recognition.

Geometric properties, also called constraints in this documentation, can be modified by the user thanks to editing gestures and value input.

Use cases

See below a few integration examples.

The input box is a Math Widget feature and cannot be reproduced with Geometry Widget only. Note that all available features are listed in the API.

Education

In this scenario, the user handwrites a shape, labels its vertices, modifies it using constraints such as segment length, angle width, parallelism and perpendicularity. The shape is automatically beautified and updated with these constraints.

Interior decoration

In this scenario, the user designs furniture by combining handwritten shapes that are then beautified and by setting their size using constraints.

Features

Geometry input
Canvas where the user can draw geometrical figures freehand.

Real-time shape recognition and beautification
Real-time recognition and beautification of shapes taking into account remarkable angles, alignment attraction (vertical/horizontal/parallel/perpendicular), congruence and connection attraction.

Constraint detection
Real-time detection of identical angles and/or segment values, horizontality, verticality, perpendicularity, parallelism, junction/connection, congruence.

Editing gestures
Gestures for perpendicularity, parallelism, junction/connection, equality of angles and/or lengths, circumference can be applied onto the recognized shapes. Undo/redo features are supported.

Segment length and angle value input
Segment lengths and angle values can be edited. Segments/angles are automatically updated and properly rendered.

Serialization
Resulting geometrical figures can be saved to be reloaded for later editing. They can also be exported as images.

Supported shapes

User action  Gesture
Circle
Circular arc
Ellipse
Elliptical arc
Parallelogram
Point (cross in one stroke)
Point (small and empty circle)
Point (scribble)
Polygon
Polyline
Quadrilateral
Rectangle
Rhombus
Segment
Square
Trapezoid
Triangle

Supported gestures

User action  Gesture Description Code sample 
Single tap Briefly touch an item Select the item
Scratch-out Scratch out an item Erase

Supported constraints

A defined set of geometric constraints is supported by the Geometry Widget. There are two types of constraints:

  • implicit: The constraint is automatically detected when a shape is created.
  • explicit:The user draws a gesture to set a constraint.

Explicit constraints are stronger than implicit constraints. By combining the shape creation and geometric constraints, the user can create a complex geometric construction.

Implicit and explicit constraints can be shown on the figure with specific symbols and are displayed with a different color:

  • blue for implicit right angle,
  • one from a set of 10 colors for explicit constraints (by pair for same length/angle).

The following table shows which constraints are supported and the various ways to define them:

Constraint  Implicit creation Explicit creation 
Angle value n/a Input the angle value.
Concentricity Two circles whose centers are close. Circle two circles’ centers.
Connection An extremity or point connected to another shape or point. Small circle on the two shapes or segments to be joined. You can also circle a segment crossing a circle to indicate it is the diameter.
Equality of angles Any shape that has two or more equal angles. Remarkable line: bisector. Angle mark gesture on two segments (one time on two different angles), to indicate that they are equal.
Equality of lengths Any shape that has two or more equal segments. Short line gesture on a segment or circle (one time on two different shapes), to indicate that their lengths are equal.
Horizontal An almost horizontal segment. n/a
Junction Extremities of shapes or segments that have been drawn very close. Note that points are regarded as extremities here. Small circle/ellipse on the two shapes or segments to be joined. You can also circle: a) a point inside a circle to indicate it is the center, b) a segment inside a circle to indicate it is a radius.
Length value n/a Input the segment length.
Parallelism Any shape that has two or more parallel segments. One chevron on two different segments, to indicate that they are parallel.
Perpendicularity Any shape that has at least one right angle. Remarkable lines: altitude and perpendicular bisector. Right angle gesture (chevron) in one stroke.
Radius equality Two circles with two similar diameters. See Equality of lengths.
Vertical An almost vertical segment. n/a

Recommendations

The default settings provided in the code sample have been defined to provide the best user experience related to geometry exercises for middle school level. Feel free to adapt those settings according to your use case, as your app may have other requirements.

Small strokes rejection

This value is set to avoid small strokes. It means that strokes smaller than the defined value will be recognized as dots.

If you increase the value, you will detect more dots. If you decrease it, you will detect smaller strokes, but dot input will be harder.

Ellipse and circle recognition

This value is set to ease the drawing of large circles, but can be updated according to your needs. The higher the value, the more likely the widget will recognize circles rather than ellipses. The lower the value, the more the widget will give accurate recognition of all kinds of ellipses and circles.

Detection and display for implicit and explicit constraints

Both implicit and explicit constraints’ detection and display features can be enabled or disabled. The default values are set to:

  • ease the recognition of geometric properties and help the user to draw right angles, parallels, same-length segments, freehand or by using explicit gestures.
  • help the user to learn gestures.
  • avoid a visual overload of the canvas with explicit constraints.

Implicit constraints are mainly a drawing assistance. They are automatically detected by the widget and quickly fade out. We recommend making implicit constraints fade out because they can be confused with explicit constraints. They do have the same graphic design but not the same behavior. We also suggest you add a button to let the user display implicit constraints on demand.

Explicit constraints are to be manually set and have priority over implicit constraints. New explicit constraints have priority over previous constraints.

You can also choose to disable the implicit constraints’ detection and display features.

To erase an explicit constraint, the display feature for explicit constraints has to be enabled.

In the below figures, you can see examples of detection and display feature for implicit constraints.

Fig.01: Detection and display are disabled.
Fig.02: Detection is enabled but display is not.
Fig.03: Both detection and display are enabled.
All constraint types can be enabled or disabled independently of each other.

Point size

The point size value is set to be visible:

  • on lines crossing.
  • on large lines (up to 3pt).
  • on explicit constraints.

Adjacent angle marker

This value is set to offer a graphic rendering that is visible with adjacent angles and clearly differentiated from the drawing.

Equality of lengths

This value is set to offer a graphic rendering that is visible over lines and clearly differentiated from the drawing.

We recommend that you do not set the value too high.

Set of colors

The defined set of colors is set to:

  • be differentiated from each other,
  • be distinguished by color-blind people (deuteranopia, protanopia, tritanopia).
We strongly recommend not modifying those colors.

Stroke display

The stroke display value is set to:

  • keep a clean and precise drawing with light thickness,
  • be distinguishable from implicit and explicit constraints, as it is defined in a different neutral color.
If you want to allow the user to draw with different colors, be careful to keep their constraints visible and understandable.

Integration

General information about ATK (licenses, samples, etc.) is available in the ATK Overview section.
Please make sure to use the latest version of Xcode and iOS SDK. Minimum deployment target is 8.0.

Step 1 - Download your Certificate

  1. Log in at https://atk.myscript.com.
  2. In the Applications tab, click Create application.
  3. Enter your application name and its description, then click Create.
  4. Click Open, then Create certificate.
  5. Enter the bundle identifier that can be found in your project’s properties (General tab) and select the target environment, then click Create.
  6. Click on the .c download icon to download the corresponding certificate.
  7. Paste it in your project and start creating your app.
You need one certificate per application and per platform. You can integrate several widgets in one application.

Step 2 - Build Settings

In the Build Settings tab of your target project:

  • Go to the Other Linker Flags section and add the following flags:
    • -ObjC
    • -lstdc++
  • Go to the Framework Search Paths section and add the path to the Frameworks directory of your package.

Step 3 - Configure your Dependencies

In the Build Phases tab of your target project:

  • Go to the Link Binary With Libraries section and add the following frameworks:

    • SystemConfiguration.framework
    • ATKGeometryWidget.framework
    • ATKGeometry.framework
    • ATKCore.framework

They can be found in the Frameworks directory of your package.

It is essential that ATKCore.framework is the last framework to be linked. To do so, make sure it is displayed at the end of the list.

Step 4 - Add Resources

In the Build Phases tab of your target project:

  • Go to the Copy Bundle Resources section and add the following:

    • ATKGeometryWidget.bundle from the Frameworks directory (images),
    • resources.bundle from the Samples/GeometryWidgetSample/GeometryWidgetSample/Resources directory (recognition configuration and resources),
    • css directory from the Samples/GeometryWidgetSample/GeometryWidgetSample/Resources directory (ink style properties).
Resources are available for download on the Developer Portal.

Step 5 - Start with Minimal Integration Code

An Internet connection is required to launch and run ATK applications. However, a 30-day grace period is offered, from the moment you first launch your application. A connection will then be mandatory.

Edit the ViewController class:

#import <ATKGeometryWidget/GWGeometryWidget.h>

@interface ViewController : UIViewController <GWGeometryViewDelegate>

@property (strong, nonatomic) IBOutlet GWGeometryView *geometryView;
@property (assign, nonatomic) BOOL certificateRegistered;

@end
#import "ViewController.h"

#import "MyCertificate.h"

@implementation ViewController

- (void)viewDidLoad
{
  [super viewDidLoad];

  // Register MyScript certificate before anything else
  NSData  *certificate = [NSData dataWithBytes:myCertificate.bytes length:myCertificate.length];
  _certificateRegistered = [_geometryView registerCertificate:certificate];

  if(_certificateRegistered)
  {
    // Register as delegate to be notified of configuration, recognition, ...
    _geometryView.delegate = self;

    NSBundle *mainBundle = [NSBundle mainBundle];
    NSString *bundlePath = [mainBundle pathForResource:@"resources" ofType:@"bundle"];
    bundlePath = [bundlePath stringByAppendingPathComponent:@"conf"];
    [_geometryView addSearchDir:bundlePath];
    
    // The configuration is an asynchronous operation. Callbacks are provided to 
    // monitor the beginning and end of the configuration process.
    //
    // "shape" references the shape bundle name in conf/shape.conf file in your resources bundle.
    // "standard" references the configuration name in shape.conf
    [_geometryView configureWithBundle:@"shape" andConfig:@"standard"];
  }
}

- (void)viewDidAppear:(BOOL)animated
{
  [super viewDidAppear:animated];

  if(!_certificateRegistered)
  {
    UIAlertController *alertController = [UIAlertController
                                          alertControllerWithTitle:@"Invalid certificate"
                                          message:@"Please use a valid certificate."
                                          preferredStyle:UIAlertControllerStyleAlert];
    UIAlertAction *okAction = [UIAlertAction
                               actionWithTitle:@"Ok"
                               style:UIAlertActionStyleDefault
                               handler:nil];
    [alertController addAction:okAction];
    [self presentViewController:alertController animated:YES completion:nil];
  }
}

- (void)geometryViewDidEndConfiguration:(GWGeometryView *)geometryView
{
  NSLog(@"Geometry Widget configured!");
}

- (void)geometryView:(GWGeometryView *)geometryView didFailConfigurationWithError:(NSError *)error
{
  NSLog(@"Unable to configure the Geometry Widget: %@", [error localizedDescription]);
}

- (void)geometryViewDidEndRecognition:(GWGeometryView *)geometryView
{
  NSLog(@"Geometry Widget recognition");
}

@end

You can then use the GWGeometryView as any UIView and add it in your ViewController using the Interface Builder (Storyboard).

API

See the API documentation for iOS.