DynamicXray

DynamicXray is a UIKit Dynamics runtime visualisation and introspection library for iOS.

Ever wanted to see under the hood of the UIKit Dynamics physics engine? Now you can! With DynamicXray you can visualise your dynamic animator live at runtime, exposing all dynamic behaviours and dynamic items.

The DynamicXray project includes a catalog of open source UIKit Dynamics demonstrations, all with DynamicXray already integrated. See DynamicXray Catalog.

Quick Start

Download the Framework binary:

Download the latest binary release.

Or build the Framework from source:

Download or clone the source code.

Open DynamicXray.xcworkspace, select the Framework scheme, build the framework.

If successful, a Finder window should open at the location of DynamicXray.framework.

Add to your project:

Add DynamicXray.framework to your iOS project.

Open your target's build settings, search for "Other Linker Flags" and add -ObjC if not already specified.

In your code, import the header and add an instance of DynamicXray to your dynamic animator.

#import <DynamicXray/DynamicXray.h>
...
DynamicXray *xray = [[DynamicXray alloc] init];
[self.dynamicAnimator addBehavior:xray];

Dynamic Library

For advanced users, the Framework script also builds DynamicXray.dylib. The dylib can be used for conditional loading at runtime, or injecting into other processes, etc.

Overview

DynamicXray is implemented as a UIDynamicBehavior. This means it can simply be added to any UIDynamicAnimator to enable the introspection overlay. By default, all behaviours owned by the animator will be visualised.

For more control, the DynamicXray behaviour exposes options such as temporarily disabling the overlay, adjusting the cross fade between app and overlay, whether to draw dynamic item outlines, and more. Refer to the DynamicXray header.

DynamicXray includes a built-in configuration panel that slides up from the bottom of the screen. The configuration panel provides access to some options at runtime. The configuration panel can be presented by calling -[DynamicXray presentConfigurationViewController].

For example:

DynamicXray *xray = [[DynamicXray alloc] init];
[self.dynamicAnimator addBehavior:xray];
[xray presentConfigurationViewController];

Features

• Easy and controllable integration. Simply add the DynamicXray behavior to your dynamic animator.

• All UIKit Dynamic behaviours are visualised, including collision boundaries.

• Visually differentiate between springy and rigid attachment behaviours.

• Push behaviours are visualised by arrows representing the location, magnitude and direction of the push force.

• Snap behaviours are visualised by arrows showing where the item is snapping to.

• Gravity behaviours are visualised by an overlay showing magnitude and direction.

• All dynamic item bodies in the scene are visualised.

• Any contacts between dynamic items and other items or collision boundaries are highlighted.

• Configurable overlay cross fade control, fading between 100% application to 100% DynamicXray overlay.

• Built-in configuration panel for user to control run-time options.

DynamicXray Catalog

The included project DynamicXrayCatalog is a universal iOS app containing a suite of various UIKit Dynamics demonstrations. The demos include DynamicXray pre-loaded so introspection can be enabled on any demo to see the inner workings.

The demos in DynamicXrayCatalog were created by various authors and all are open source.

Contributions are welcome! Submit a pull request if you would like to contribute a demo to DynamicXrayCatalog. Please make sure that your demo includes an option to enable DynamicXray.

Videos

See DynamicXray demonstration videos on YouTube.

Copyright and Licenses

DynamicXray is Copyright (c) Chris Miles 2013-2014 and available for use under a GPL-3.0 license.

The DynamicXray icon and any other included artwork is Copyright (c) Chris Miles 2013-2014 and available for use under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0) only when used along with the DynamicXray library.

DynamicXrayCatalog is Copyright (c) Chris Miles 2013-2014 and others. DynamicXrayCatalog contains source code copyrighted by others and included within the terms of the respective licenses. See the included project sources for more details.

DynamicXrayCatalog is available for use under a BSD (2-Clause) License, except for where included source code specifies alternative license details, then that code remains available under the original license terms. Refer to the source code for more details.