Brendan Innis

Building Your First App for visionOS: Part 2

2024-09-25T00:00:00Z

In part 1 of this tutorial, you learned how to set up a new visionOS project and create a basic user interface using SwiftUI. In this part, you'll learn how to use RealityKit and SwiftUI to display and animate a 3D bar chart in a visionOS app.

You can pickup this tutorial using the code you wrote in part 1, or download the finished project from part 1 here. After part 1 you should have a project that looks like this:

Adding a 3D bar chart #

When the user toggles the “Show Chart” button we're going to draw a 3D bar chart representing our data in the volumetric window. Since our chart will be made up of a collection of 3D objects, we'll create a root Entity in our AppState that will hold all the chart objects.

 // AppState.swift
 import Foundation
+import RealityKit

 @Observable
 public class AppState {
     var isShowingChart = false
     var chartTitle = ""
     var chartContent: ChartContent = []
+    var chart = Entity()
+
+    init() {
+        // Position the chart near the bottom of the volume
+        chart.transform.translation.y -= 0.23
+    }
 }

Entity is a holder for 3D objects in RealityKit. We're going to make all the entities in our chart children of this root entity, that way we can manipulate the entire chart as a single object. When we first add the chart: Entity to the RealityView it's position (translation) will be in the center of the volume. Since our volume is 0.5 meters in height we move the chart down by 0.23 meters to position it near the bottom of the volume. It's helpful to keep in mind the coordinate space:

Next, we'll add the chart to our RealityView:

 // ChartView.swift
 struct ChartView: View {

     var body: some View {
         RealityView { content in
-            if let entity = await loadEntity() {
-                content.add(entity)
-                entity.transform.translation.y -= 0.1
-            }
+            content.add(appState.chart)
+        } update: { content in
+            appState.updateChart()
         }
         .toolbar {
             ToolbarItemGroup(placement: .bottomOrnament) {

We've also added an update block to our RealityView. This allows us to update the chart when the app state changes. Any changes to app state properties within updateChart will cause update to be called. We'll implement updateChart in a moment.

Drawing the chart #

Before we draw the chart, we need to add to an Entity to our ChartData to represent each cell as a 3D object. Open ChartContent.swift and add the following code:

 // ChartContent.swift
 
 import Foundation
+import RealityKit

 /// Represents a cell in the chart
 @Observable
 class ChartData {
     /// The value held this cell in the chart
     var value: String
     /// The value as a `Float` or `0` if not a number
     var floatValue: Float {
         Float(value) ?? 0
     }
+    /// Represents the data as a 3D object in a RealityKit scene
+    var entity: Entity?

     init(value: String) {
         self.value = value

NOTE: We're going to make some assumptions about our chart:

We're going to treat the first ChartRow as a row of headings for one axis of the chart.
The first ChartData in each row will be the headings for the other axis.
We'll also assume that all the values in the chart are positive numbers.

Create a new Swift file called AppState+ChartDrawing.swift and add the following code:

// AppState+ChartDrawing.swift

import Foundation
import UIKit
import RealityKit

fileprivate extension ChartContent {
    var maxChartValue: Float {
        var result: Float = 0
        // Drop headings
        for row in dropFirst() {
            for col in row.data.dropFirst() {
                result = Swift.max(result, col.floatValue)
            }
        }
        if result <= 0 {
            result = 1
        }
        return result
    }
}

fileprivate var chartBoundsDidChange = true

extension AppState {
    /// The width and depth of a bar in meters
    private var barSize: Float { 0.05 }
    /// The height of a bar in meters
    private var barHeight: Float { barSize * 5 }
    /// The size of the gutters in between the bars
    private var barPadding: Float { barSize * 0.8 }
    /// The minimum height of a bar
    private var minBarScale: Float { 0.042 }
    
    private enum ChartColors {
        case red
        case yellow
        case green
        case blue
        
        var uiColor: UIColor {
            switch self {
            case .red:
                return .red
            case .yellow:
                return .yellow
            case .green:
                return .green
            case .blue:
                return .blue
            }
        }
                
        static var all: [ChartColors] {
            [
                .red,
                .yellow,
                .green,
                .blue,
            ]
        }
    }

    func updateChart() {
        // Calculate the greatest value to determine the height of the chart
        let maxChartValue = chartContent.maxChartValue
        
        chartContent.dropFirst().enumerated().forEach { rowIndex, row in
            draw(chartRow: row,
                 maxChartValue: maxChartValue,
                 rowIndex: rowIndex)
        }
        
        if chartBoundsDidChange {
            let bounds = chart.visualBounds(relativeTo: nil).extents
                        
            // Position the middle of the chart in the middle of the volumne
            chart.transform.translation.x = -1 * bounds.x * 0.5
            chart.transform.translation.z = -1 * bounds.z * 0.5
            
            chartBoundsDidChange = false
        }
    }
    
    private func draw(chartRow row: ChartRow,
                      maxChartValue: Float,
                      rowIndex: Int) {
        let color = ChartColors.all[rowIndex].uiColor
        
        row.data.dropFirst().enumerated().forEach { colIndex, data in
            // Determines the height of the bar
            let scale = max(data.floatValue / maxChartValue, minBarScale)
            
            drawCell(data: data,
                     scale: scale,
                     color: color,
                     rowIndex: rowIndex,
                     colIndex: colIndex)
        }
    }
    
    private func drawCell(data: ChartData,
                          scale: Float,
                          color: UIColor,
                          rowIndex: Int,
                          colIndex: Int) {
        // Create the entity if needed
        let entity = data.entity ?? {
            chartBoundsDidChange = true

            // Create a model entity for the bar
            let mesh = MeshResource.generateBox(width: barSize,
                                                height: barHeight,
                                                depth: barSize)
            let colorMaterial = SimpleMaterial(color: color,
                                               roughness: 0.3,
                                               isMetallic: false)
            let entity = ModelEntity(mesh: mesh, materials: [colorMaterial])
            
            // Set the height of the bar
            entity.transform.scale.y = scale
            // Align the bars vertically
            entity.transform.translation.y = barHeight * scale * 0.5
 
            // Position the bar in row and column position
            let x = (barSize + barPadding) * Float(colIndex) + barSize * 0.5
            let z = (barSize + barPadding) * Float(rowIndex) + barSize * 0.5
            entity.transform.translation.x = x
            entity.transform.translation.z = z
            
            // Add the entity to the chart
            chart.addChild(entity)
            
            // Store the new entity in this ChartData
            data.entity = entity
            
            return entity
        }()

        // Change the height of the bar if needed
        if entity.transform.scale.y != scale {
            var transform = entity.transform
            transform.scale.y = scale
            transform.translation.y = barHeight * scale * 0.5
            // Animate the bar height changes
            let anim = FromToByAnimation(from: entity.transform,
                                         to: transform,
                                         bindTarget: .transform)
            if let res = try? AnimationResource.generate(with: anim) {
                entity.playAnimation(res)
            }
        }
    }
}

For each cell we create a ModelEntity representing a bar in the chart using MeshResource to generate a box shape and SimpleMaterial to give it some color. We modify the entity transform to position each bar in row and column position, set it's height and align the bars so that they sit on the floor of the volume. When the height of a bar changes we use a simple UIKit animation to animate the change.

Run the app and you should see a 3D bar chart in the volumetric window. Make changes to the data to see the chart update. The app should look like this:

Drawing a base plate #

The next thing we want is to be able to label the chart. We'll start by adding a base plate to the chart so our text will stand out and the chart will feel more cohesive.

First, modify the AppState.swift file to include a new stored property for our base plate:

 // AppState.swift
 public class AppState {
     var chartTitle = ""
     var chartContent: ChartContent = []
     var chart = Entity()
+    var basePlate: Entity?

     init() {
         // Position the chart near the bottom of the volume

Next, we'll make a few modifications to AppState+ChartDrawing.swift.

First we add new properties to the AppState extension for the base plate:

 // AppState+ChartDrawing.swift
     private var barPadding: Float { barSize * 0.8 }
     /// The minimum height of a bar
     private var minBarScale: Float { 0.042 }
+    /// The distance between the edge of the base plate and the chart content
+    private var basePlatePadding: Float { 0.1 }
+    /// The thickness of the base plate
+    private var basePlateHeight: Float { 0.02 }

     private enum ChartColors {
         case red

Then we'll call a new method in updateChart when the chart bounds change to draw the base plate:

         if chartBoundsDidChange {
+            basePlate?.removeFromParent()

             let bounds = chart.visualBounds(relativeTo: nil).extents

+            drawBasePlate(inBounds: bounds)
+
             // Position the middle of the chart in the middle of the volumne
             chart.transform.translation.x = -1 * bounds.x * 0.5
             chart.transform.translation.z = -1 * bounds.z * 0.5

We have to remove the base plate from the chart before we calculate the chart bounds, otherwise the base plate will include itself and grow each time the chart bounds change.

Finally, we'll implement the drawBasePlate method:

private func drawBasePlate(inBounds bounds: SIMD3<Float>) {
    // Add padding to the chart bounds
    let basePlateBounds = bounds + SIMD3<Float>(repeating: basePlatePadding)

    let mesh = MeshResource.generateBox(width: basePlateBounds.x,
                                        height: basePlateHeight,
                                        depth: basePlateBounds.z,
                                        cornerRadius: basePlateHeight * 0.5)
    let colorMaterial = SimpleMaterial(color: .white,
                                       roughness: 0.1,
                                       isMetallic: false)
    let basePlate = ModelEntity(mesh: mesh, materials: [colorMaterial])
    chart.addChild(basePlate)

    // Position the middle of the base plate in the middle of the chart
    basePlate.transform.translation.x += bounds.x * 0.5
    basePlate.transform.translation.z += bounds.z * 0.5

    self.basePlate = basePlate
}

We use the chart bounds to calculate the size of the base plate based on the content of the 3D chart. The bounds of the chart include the bounds all it's descendants, so it is convenient to use this to calculate the size required for the base plate.

Labelling the rows #

We want to draw 3D text on our chart to label the axes. Remember we are considering the first row of the chart to be the headings for one axis and the first column in each row to be the headings for the other axis. We'll draw the headings for the first row after the other rows so it is toward the user in the z-direction. We'll draw the headings for each row after each row in the x-direction because it makes the chart positions easy to calculate.

Call a new method called drawHeading for each chart row:

 // AppState+ChartDrawing.swift
     private func draw(chartRow row: ChartRow,
                       maxChartValue: Float,
                       rowIndex: Int) {
         let color = ChartColors.all[rowIndex].uiColor

         row.data.dropFirst().enumerated().forEach { colIndex, data in
             // Determines the height of the bar
             let scale = max(data.floatValue / maxChartValue, minBarScale)

             drawCell(data: data,
                      scale: scale,
                      color: color,
                      rowIndex: rowIndex,
                      colIndex: colIndex)
         }
+
+        drawHeading(forChartRow: row, rowIndex: rowIndex)
     }

Implement the new method to draw the headings:

private func drawHeading(forChartRow row: ChartRow, rowIndex: Int) {
    guard let heading = row.data.first else {
        assertionFailure("ChartRow should have a heading")
        return
    }

    // If the heading value changed, remove the entity and redraw it
    if let entity = heading.entity,
       entity.name != heading.value
    {
        chart.removeChild(entity)
        heading.entity = nil
    }

    // Create a new heading entity if needed
    _ = heading.entity ?? {
        chartBoundsDidChange = true
        
        let entity = createLabelEntity(forHeading: heading)
        chart.addChild(entity)

        // Position the heading after the row
        let bounds = entity.visualBounds(relativeTo: nil).extents
        let cellSize = barSize + barPadding
        let rowMaxX = cellSize * Float(row.data.count - 1) - barPadding
        let rowZ = cellSize * Float(rowIndex)
        entity.transform.translation.y = basePlateHeight * 0.5
        entity.transform.translation.x = rowMaxX + basePlatePadding * 0.25
        entity.transform.translation.z = rowZ + barSize - bounds.y
            
        return entity
    }()
}
    
private func createLabelEntity(forHeading heading: ChartData) -> Entity {
    let mesh = MeshResource.generateText(heading.value,
                                         extrusionDepth: 2)
    let colorMaterial = SimpleMaterial(color: .black,
                                       isMetallic: false)
    let entity = ModelEntity(mesh: mesh, materials: [colorMaterial])

    // Store the heading value in the name to compare later
    entity.name = heading.value
    // Size the text appropriately for the chart
    entity.scale *= 0.002
    // Rotate the text by 90 degrees to lay flat
    entity.orientation = simd_quatf(angle: -1 * .pi * 0.5,
                                    axis: [1, 0, 0])
    // Store the new entity in this ChartData
    heading.entity = entity

    return entity
}

When we create text mesh using MeshResource.generateText the text will be vertically oriented along the y-axis from the user's perspective. We rotate the text by 90 degrees around the x-axis to lay it flat on the base plate. This can be done in a few ways but here we use a simple quaternion to set the appropriate orientation. When we position the text along the z-axis we are using the y bounds of the text entity since we rotated it.

Now run the app and you should see the headings appear after each row on the base plate. When you make a change to the row label the 3D chart should update and redraw.

Labelling the columns #

Now we're going to draw the headings for the columns contained in the first row of chart data. We'll draw the column headings after the data rows. First, call a new method after the chart rows are drawn:

 // AppState+ChartDrawing.swift
     func updateChart() {
         // Calculate the greatest value to determine the height of the chart
         let maxChartValue = chartContent.maxChartValue

         chartContent.dropFirst().enumerated().forEach { rowIndex, row in
             draw(chartRow: row,
                  maxChartValue: maxChartValue,
                  rowIndex: rowIndex)
         }

+        drawChartHeadings()
+
         if chartBoundsDidChange {
             basePlate?.removeFromParent()

Next we'll draw the column headings, reusing the existing createLabelEntity method:

private func drawChartHeadings() {
    guard let headingsRow = chartContent.first else {
        assertionFailure("A chart should always have at least one row")
        return
    }
        
    let rowCount = chartContent.count - 1
    headingsRow.data.dropFirst().enumerated().forEach { colIndex, column in
        // If the heading value changed, remove the entity and redraw
        if let entity = column.entity, 
           entity.name != column.value
        {
            chart.removeChild(entity)
            column.entity = nil
        }
            
        // Create a new heading entity if needed
        _ = column.entity ?? {
            chartBoundsDidChange = true
            let entity = createLabelEntity(forHeading: column)
            chart.addChild(entity)

            // Position the heading row after the other rows
            let bounds = entity.visualBounds(relativeTo: nil).extents
            let cellSize = barSize + barPadding
            let colX = cellSize * Float(colIndex) + barSize * 0.5
            let colMaxZ = cellSize * Float(rowCount) - barPadding
            let y = basePlateHeight * 0.5
            let x = colX - bounds.x * 0.5
            let z = colMaxZ + barSize * 0.5 + basePlatePadding * 0.25
            entity.transform.translation.y = y
            entity.transform.translation.x = x
            entity.transform.translation.z = z
                
            return entity
        }()
    }
}

Testing the 3D chart #

We now have a functional labelled 3D bar chart that updates when the data changes. Run the app and see what the chart looks like. Play around with it and trying changing various values to see how it behaves. At this point the chart should look like this:

You might notice some limitations of the chart. For example, the column headings will quickly run into each other if they contain too much text. If you create a very long row label, then the chart will become too large to fit in the 3D volume and will be clipped by the window. The chart also would represent values very well if one value is much larger than the others. It would also be nice to have a mechanism to add and delete rows and columns from the chart.

Test out the app yourself and see if you can find any other issues or room for improvement. It's important to continuously run and test your app as well as get feedback from users so your app will consistently improve.

Next Steps #

You've now learned everything you need to know to create a basic visionOS app. You've learned how to create flat and volumetric windows and populate them using SwiftUI views and RealityKit entities. You've learned how to represent your data as app state to keep your UI in sync and animate updates. You've also learned how to create basic meshes and materials and how to manipulate them in a 3D scene. Further tutorials in this series will expand on the capabilities of visionOS and add depth to your app.

You can download the finished project from part 2 of the tutorial here. The full source code for the 3D charts tutorial can be found on GitHub.

In part 3 we will add functionality to the app and improve the visuals of the 3D chart.

Building Your First App for visionOS: Part 1

2024-09-20T00:00:00Z

In this tutorial series you will learn how to build a complete app for visionOS using SwiftUI and RealityKit. You will learn how to create a new visionOS project, how to build an interface for visionOS using SwiftUI and how to display and animate 3D content using RealityKit. This tutorial will get you started building apps for visionOS right away and provide a solid foundation to learn from.

We will build a spreadsheet app that displays 3D charts. The app will include a spreadsheet like interface and a 3D bar chart. It will look something like this:

New visionOS project #

To create a new visionOS project, open Xcode and select File/New/Project (⇧⌘N). Select the “visionOS” tab and choose the “App” template.

Click “Next” and then choose options for your new project:

Product Name: 3D Charts (This will be the name of your app)
Team: [Your Team] (You will need to sign in with your Apple ID if you haven't already)
Organization Identifier: [Your reversed domain] (To uniquely identify your app)
Initial Scene: Window (We'll display our spreadsheet using SwiftUI)
Immersive Space Renderer: None (We're going to display our 3D content in a Volumetric Window)
Immersive Space: Mixed (We can introduce a mixed reality space later in the project)

Exploring the new visionOS project #

The template visionOS project creates an app that shows a 3D model in a window using SwiftUI. The project also includes a Reality Composer Pro package called RealityKitContent that includes a scene with a 3D model and texture. Reality Composer Pro is a standard way to include 3D content in your visionOS app. It can be found by selecting Xcode/Open Developer Tool/Reality Composer Pro.

The first thing you should do when you create a new project is to run it and understand how the code works. Press “Run” and let Xcode boot up the visionOS simulator and launch the app. Once you've launched the app and confirmed that it runs, we can start making changes.

Starting from scratch #

Since I chose “3D Charts” as the name of my app, I have to clean up my App file a bit. We can also add a volumetric window that we'll use later to display the 3d charts.

Select the App file in the project navigator:

Make changes to the App file:

Rename the App struct to ThreeDeeChartsApp and the file to ThreeDeeChartsApp.swift.
Create a new @State property called appState and set it as the environment for ContentView.
Create an empty volumetric window that we'll use later to display the 3D charts.

// After
import SwiftUI

@main
struct ThreeDeeChartsApp: App {
    @State private var appState = AppState()
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(appState)
        }
        .windowResizability(.contentSize)
        
        WindowGroup {
            // 3D charts will go here
        }
        .windowStyle(.volumetric)
    }
}

Create a new file called AppState.swift. AppState will be an @Observable class to keep track of our app state including the chart data and UI state. For now, we'll add a String to keep track of our chart's title.

// AppState.swift
import Foundation

@Observable
public class AppState {
    var chartTitle = ""
}

Open the ContentView.swift file.

Create an @Environment property to access the AppState object.
We're going to create a vertical stack of the app title, the chart title and the chart data. We'll add some basic styling for now and add a glassBackgroundEffet() to the preview so we can easy see the UI rendered in Xcode canvas.
We also need to make the appState bindable so the TextField can update the chartTitle property.

// ContentView.swift
import SwiftUI

struct ContentView: View {
    @Environment(AppState.self) private var appState
    
    var body: some View {
        @Bindable var appState = appState
        VStack(alignment: .leading) {
            Text("3D Charts")
                .font(.extraLargeTitle)
                .padding(.bottom, Constants.verticalSpacing)
            TextField("Chart Title", text: $appState.chartTitle)
                .font(.title)
                .frame(maxWidth: 480)
                .padding(.bottom, Constants.verticalSpacing)

        }
        .padding(EdgeInsets(top: Constants.verticalSpacing,
                            leading: Constants.horizontalMargin,
                            bottom: Constants.verticalSpacing,
                            trailing: Constants.horizontalMargin))
    }
}

#Preview {
    return ContentView()
        .glassBackgroundEffect()
        .environment(AppState())
}

Finally, create a Constants.swift file to store some values we'll reuse throughout the app.

// Constants.swift
import Foundation

enum Constants {
    static let verticalSpacing: CGFloat = 8
    static let horizontalMargin: CGFloat = 48
}

Now switch back to ContentView.swift and enable the Canvas by selecting it from the “Adjust Editor Options” menu in the top right corner of the Xcode window (⌥⌘↩). The Canvas is useful for previewing changes to your SwiftUI code as you write it. You can also interact with the “Chart Title” TextField and change it's value.

Building the spreadsheet UI #

We need a way to enter data for our 3D charts. We're going to create a grid of rows and columns with text fields where the user can enter data and store that data in our AppState.

First create a new file called ChartContent.swift. We'll create some data structures to contain our chart data. We store the chart data as a string so we can hold values like headings, but we'll add a property to access the value as a Float which we can use to draw our chart. We're going to make the data @Observable so the UI will be updated when the data changes.

// ChartContent.swift
import Foundation

/// Represents a cell in the chart
@Observable
class ChartData {
    /// The value held this cell in the chart
    var value: String
    /// The value as a `Float` or `0` if not a number
    var floatValue: Float {
        Float(value) ?? 0
    }
    
    init(value: String) {
        self.value = value
    }
}

/// Represents a row of chart data
@Observable
class ChartRow {
    /// The data held in each column of this row
    var data: [ChartData]
    
    init(data: [ChartData]) {
        self.data = data
    }
}

/// Represents all the data held in the chart
typealias ChartContent = [ChartRow]

Now we're going to add the chart content to our app state. Open AppState.swift and add a new property called chartContent to hold the chart data. We'll also add a method to create some default data for our chart. This will make it easier to debug our UI in the Canvas Preview.

 // AppState.swift
 @Observable
 public class AppState {
     var chartTitle = ""
+    var chartContent: ChartContent = []
 }
+
+#if DEBUG
+extension AppState {
+    func preloadAppState() {
+        chartTitle = "Favourite Colour by Age"
+        chartContent = [
+            ChartRow(data: [ChartData(value: "Age Range"),
+                            ChartData(value: "1-20"),
+                            ChartData(value: "21-40"),
+                            ChartData(value: "41-60"),
+                            ChartData(value: "61-80")]),
+            ChartRow(data: [ChartData(value: "Red"),
+                            ChartData(value: "15"),
+                            ChartData(value: "55"),
+                            ChartData(value: "16"),
+                            ChartData(value: "12")]),
+            ChartRow(data: [ChartData(value: "Yellow"),
+                            ChartData(value: "5"),
+                            ChartData(value: "15"),
+                            ChartData(value: "38"),
+                            ChartData(value: "40")]),
+            ChartRow(data: [ChartData(value: "Green"),
+                            ChartData(value: "20"),
+                            ChartData(value: "20"),
+                            ChartData(value: "32"),
+                            ChartData(value: "18")]),
+            ChartRow(data: [ChartData(value: "Blue"),
+                            ChartData(value: "60"),
+                            ChartData(value: "10"),
+                            ChartData(value: "14"),
+                            ChartData(value: "30")]),
+        ]
+    }
+}
+#endif

Let's build the spreadsheet UI. Create a new SwiftUI View file called Spreadsheet.swift. We're going to display our chart content in a SwiftUI Grid with the cells as editable TextField views so we can make changes to the data in our chart. We'll also add a divider after the first row to separate the headings from the data. Finally, we'll extend Constants with values that will only be used in the Spreadsheet view and set up a #Preview with our sample data along with some padding and background effect for readability.

// Spreadsheet.swift
import SwiftUI

struct Spreadsheet: View {
    @Environment(AppState.self) private var appState

    var body: some View {
        Grid(alignment: .leading,
             horizontalSpacing: Constants.cellBorderWidth,
             verticalSpacing: Constants.cellBorderWidth) {
            
            ForEach(Array(appState.chartContent.enumerated()),
                    id: \.offset) { rowIndex, row in
                
                GridRow {
                    ForEach(Array(row.data.enumerated()),
                            id: \.offset) { colIndex, data in
                        
                        @Bindable var data = data
                        TextField("", text: $data.value)
                            .frame(width: Constants.cellWidth,
                                   height: Constants.cellHeight)
                    }
                }
                
                if rowIndex == 0 {
                    Divider()
                        .gridCellUnsizedAxes(.horizontal)
                        .padding(EdgeInsets(top: 0,
                                            leading: 4,
                                            bottom: 0,
                                            trailing: 4))
                }
            }
        }
    }
}

fileprivate extension Constants {
    static let cellBorderWidth: CGFloat = 4
    static let cellWidth: CGFloat = 100
    static let cellHeight: CGFloat = 32
}

#Preview {
    let appState = AppState()
    appState.preloadAppState()
    return Spreadsheet()
        .padding(EdgeInsets(top: 8, leading: 48, bottom: 8, trailing: 48))
        .glassBackgroundEffect()
        .environment(appState)
}

Now add the Spreadsheet to the bottom of the VStack in ContentView.swift. Give it the same bottom vertical padding as the other views and setup the #Preview to preload the app state.

 // ContentView.swift
                 .font(.title)
                 .frame(maxWidth: 480)
                 .padding(.bottom, Constants.verticalSpacing)
+            Spreadsheet()
+                .padding(.bottom, Constants.verticalSpacing)

         }
         .padding(EdgeInsets(top: Constants.verticalSpacing,
                             leading: Constants.horizontalMargin,
                             bottom: Constants.verticalSpacing,
                             trailing: Constants.horizontalMargin))
     }
 }

 #Preview {
+    let appState = AppState()
+    appState.preloadAppState()
     return ContentView()
         .glassBackgroundEffect()
-        .environment(AppState())
+        .environment(appState)
 }

After that, run the Canvas Preview and your UI should look something like this:

Showing 3D content in a volumetric window #

You can use RealityKit to display 3D content in the user's physical space. We're going to use a volumetric window to show our 3D chart alongside other running application windows. We'll use a RealityView to display RealityKit content in our SwiftUI app.

First, we need to keep track of whether the 3D chart is showing. Add a property called isShowingChart to AppState.swift.

 // AppState.swift
 @Observable
 public class AppState {
+    var isShowingChart = false
     var chartTitle = ""
     var chartContent: ChartContent = []
 }

Now we can create a toggle button in our UI to show and hide the 3D chart. Open ContentView.swift and add the Toggle in an HStack with the app title. We'll use a Spacer to push the Toggle to the trailing edge of the screen and use a fixedSize() modifier on the parent VStack to keep the Spacer from taking up more space than it needs.

 // ContentView.swift
 struct ContentView: View {
     var body: some View {
         @Bindable var appState = appState
         VStack(alignment: .leading) {
-            Text("3D Charts")
-                .font(.extraLargeTitle)
-                .padding(.bottom, Constants.verticalSpacing)
+            HStack {
+                Text("3D Charts")
+                    .font(.extraLargeTitle)
+                    .padding(.bottom, Constants.verticalSpacing)
+                Spacer()
+                Toggle(isOn: $appState.isShowingChart) {
+                    if appState.isShowingChart {
+                        Text("Hide Chart")
+                            .frame(minWidth: 160)
+                    } else {
+                        Text("Show Chart")
+                            .frame(minWidth: 160)
+                    }
+                }
+                .toggleStyle(.button)
+            }
             TextField("Chart Title", text: $appState.chartTitle)
                 .font(.title)
                 .frame(maxWidth: 480)
                 .padding(.bottom, Constants.verticalSpacing)
             Spreadsheet()
                 .padding(.bottom, Constants.verticalSpacing)
         }
+        .fixedSize()
         .padding(EdgeInsets(top: Constants.verticalSpacing,
                             leading: Constants.horizontalMargin,
                             bottom: Constants.verticalSpacing,

Open up your App file again. We're going to observe the state of isShowingChart and open and dismiss the volumetric window in response. We need to bring in the .openWindow and .dismissWindow environment actions to show and hide the window. We'll also pre-populate our app state when are running the app in debug, so we can easily see our spreadsheet data.

 @main
 struct ThreeDeeChartsApp: App {
-    @State private var appState = AppState()
+    @State private var appState: AppState = {
+        let appState = AppState()
+        #if DEBUG
+        appState.preloadAppState()
+        #endif
+        return appState
+    }()

+    @Environment(\.openWindow) private var openWindow
+    @Environment(\.dismissWindow) private var dismissWindow
+
     var body: some Scene {
         WindowGroup {
             ContentView()
                 .environment(appState)
+                .onChange(of: appState.isShowingChart) { oldValue, newValue in
+                    if newValue {
+                        openWindow(id: .chartWindow)
+                    } else {
+                        dismissWindow(id: .chartWindow)
+                    }
+                }
         }
+        .windowResizability(.contentSize)

-        WindowGroup {
-            // 3D charts will go here
-        }.windowStyle(.volumetric)
+        WindowGroup(id: .chartWindow) {
+            ChartView()
+                .environment(appState)
+        }
+        .windowStyle(.volumetric)
+        .defaultSize(width: 0.8, height: 0.5, depth: 0.8, in: .meters)
     }
 }
+
+typealias WindowId = String
+
+extension WindowId {
+    static let chartWindow = "ChartWindow"
+}

Finally, we'll create one more SwiftUI View file called ChartView.swift. Here, we'll import RealityKit as well as our RealityKitContent package. For now, we'll just create a RealityView and add the 3D model we still have in our content package to the scene. We will also add a toolbar window ornament to display the chart title. We also need to add an .onDisappear block to track when the 3D chart is hidden.


import SwiftUI
import RealityKit
import RealityKitContent

struct ChartView: View {
    @Environment(AppState.self) private var appState

    var body: some View {
        RealityView { content in
            if let entity = await loadEntity() {
                content.add(entity)
                entity.transform.translation.y -= 0.1
            }
        }
        .toolbar {
            ToolbarItemGroup(placement: .bottomOrnament) {
                VStack (spacing: 12) {
                    Text(appState.chartTitle)
                }
            }
        }
        .onDisappear {
            appState.isShowingChart = false
        }
    }
    
    private func loadEntity() async -> Entity? {
        try? await Entity(named: "Scene", in: realityKitContentBundle)
    }
}

#Preview(windowStyle: .volumetric) {
    ChartView()
        .environment(AppState())
}

Now run the app and try it out! You should be able to toggle the volumetric window to show the 3D content. You can also make changes to the chart title and see it reflected in the toolbar ornament of the volumetric window.

Next steps #

In part 2 of this tutorial series we will learn how to create a 3D bar chart using RealityKit and SwiftUI. You can download the finished project from this part 1 of the tutorial here.

So I rebuilt my blog using Eleventy

2024-08-30T00:00:00Z

I realized that I have more tags than I do blog posts. As of this post, that is no longer true. Thankfully I tagged this post only Web. I discovered static site generators with Jekyll, which I used to build this blog at brendaninnis.ca. Since then I've become unhappy with the version of the Hydeout theme I was using and I wanted to change up the look of my blog.

Why Eleventy? #

You want the truth? I did a Google search for “Should I use Jekyll in 2024” and found some Reddit post where someone mentions Eleventy. When I checked out Eleventy it seemed much more barebones than Jekyll so I thought I could create a custom theme with a bit more ease. I also prefer managing packages with npm over RubyGems. Switching static site generators didn't seem like much of a lift since of course I was already using Markdown for my posts.

The Good #

The getting started page had me serving a basic site without trouble. Rather than pouring through the docs I decided just to fork the Eleventy Base Blog and just start importing my posts and seeing what happened. I pulled up a couple other tutorials, but I mostly skimmed them and took things with a grain of salt since many were written for older versions of Eleventy. Within the first day I was viewing a couple of my posts in the new template and starting to modify the theme. I really think the Eleventy Base Blog is a great starting point and exploring the config files will teach you a lot about how Eleventy works, but I will caveat this with the fact that the base blog template already had outdated (deprecated) parts of Eleventy that hand't been updated to the latest version.

The Bad #

The docs at 11ty.dev barely exist and essential features of the system have just a note written about them. Additionally, there is not an excess of material written about Eleventy on the web. There were a couple of other things that tripped me up and took me some time to solve.

Images #

I first couldn't get animated images to work. A few of my blog posts have example animated GIFs to demo some code. At first using the existing eleventy-img config in the Eleventy Base Blog the animated images were appearing as a still image of the first frame. I found the Eleventy documentation does include a section on animated images but while the example code produced an animated image, the generated metadata and resulting HTML had the wrong height. The solution I found was to use Sharp to get the correct height and width of the image and then generate my own HTML to display the image. I found this blog post very helpful for learning how to generate image HTML. You can find my image configuration on my blog repo if you're interested.

Aside from my difficulty with animated images, I still have no idea how the sizes attribute works (such as the example "100vh" given in the docs). If anyone understands image config in Eleventy well I would love an explanation.

Syntax Highlighting #

This one is my fault really. I wanted to learn how to apply a custom color scheme to my code blocks. The Eleventy docs give an example of using a custom PrismJS theme here, but I had an issue where the Eleventy Base Blog was applying another theme at the same time and I couldn't figure out where it was coming from. Eventually, exploring, I found it was included from node modules in the post.njk layout, which makes sense. I removed that line, but I still can't understand how the theme ended up in node_modules in the first place. Maybe it's a dependency of the eleventy-plugin-syntaxhighlight package? Again if someone can tell me how to find out I would appreciate it.

Summing It Up #

Honestly a few times felt like I was back learning to program for the first time when I just wanted to make websites and was getting lost in a sea of JS frameworks and build tools, but after getting through a few struggles Eleventy is actually a very easy and approachable SSG. Once I had my posts working and I was able to start tinkering with the theme I was having a lot of fun. I do enjoy the build system it's fast and has a nice watch mode.

Let me know what you think!

Coding Makes You Less Creative

2023-05-04T00:00:00Z

Every time I try to come up with an interesting and unique name for a new project I start drawing blanks. I released a daily fat counter app called Daily Fat Counter for Jobs' sake. There is a tendency to attribute creativity to software engineers because they invent novel solutions to real problems, but I believe that coding makes you less creative, exactly because it forces you to be predictable, clear and objective.

An experienced developer has built habits of controlling their creativity.

Naming things and predictability #

The hallmarks of good code are that it is clear, understandable and does what you expect. This is reflected in the clear naming of things like variables, classes and methods. If you create a class to decode JSON, then it better be called JSONDecoder. If your class is called something like CrockfordsMagicBitMachine might be fun and at least a little creative, but it doesn't help the user of your class, and in fact it actively hurts them.

Want to declare a variable that will hold a URL to a resource you are interested in? Then it better be named url. Actually, it would be much better if the name was more descriptive, such as including the name of the resource you are pointing to like dog_ceo_api_url.

What you are doing here is the opposite of creativity. Instead of trying to relate disparate concepts together in the readers mind, you are trying to fix the same single objective concept in every readers mind. There should be no room for interpretation in your code.

I think doing this over and over again as a developer saps your mind of the ability to name things creatively, in a way that inspires many ideas the heads of your audience.

Concise is clean and boring is better #

If your code can do in 1000 lines what it can do in 10000 lines, then the 1000 lines is almost certainly better. The less features your software has, the better. Less is more.

These are rules are a bit arbitrary and do not always hold, but there are good reasons to follow them. More code means more bugs. The larger your codebase is, the longer it takes to work on. There is just more to read and more to understand. Programming languages themselves are abstractions that allow us to do more with less by working with broader concepts that are easier to reason about than a massive collection of smaller mechanisms. If I could write a program that consisted of a single line of text input and accomplished the goal I wanted I would.

And what about style? What about that personal artistic flair? That's a code smell. We have style guides for a reason. I want your code to be boring. I want it to read like I wrote it or anyone else wrote it because it all looks exactly the same.

This too is the opposite of creativity. Following coding conventions, style guides and design patterns is a good thing. It makes it easy for you and for others to reason about and work on your code. It is not a good idea to interchangeably mix functional and object-oriented programming styles in the same codebase or even in the same function, unless the language calls for it. While it might show off your creative spark for coding, it increases the cognitive load on your reader by forcing them to hold more concepts in their head at once than necessary.

It's not all bad #

Programming can be a creative endeavour. It forces you to think outside the box to come up with unique approaches to problem solving. You can be incredibly creative in the way that you debug your software, or produce new design patters and architectures, or use APIs in unexpected ways, but the point of this article is to illustrate the point that programming trains your brain away from creativity. It rewards you for not giving your readers a fertile ground for their imagination, and I can't help but think that's to blame every time I can't think of a cool name for my app.

Getting started with RealityKit 1: Programmatically placing content in RealityKit

2023-02-09T00:00:00Z

In this tutorial you will create an iOS app where a user can tap the screen to place 3D content in their physical environment. You will learn how to load 3D resources from files into RealityKit entities and anchor them to phsyical locations in the real world. At the end of this guide there will be a link to download the finished version of the app we are building.

Create an augmented reality app #

Open Xcode, and select "Create a new Xcode project". A window will open with a list of template to choose from. Select "Augmented Reality App" and press Next. Choose a name for your app, select SwiftUI as the value for "Interface" and RealityKit as the value for "Content Technology". Your new project should look like this:

This will create a project containing an AppDelegate.swift file, a ContentView.swift file containing our main SwiftUI layout, a template RealityKit Experience.rcproject file and a set of assets for your project.

We will not be using the AppDelegate or the RealityKit Experience, so those files should be deleted.

Create a new Swift file for your SwiftUI App. Create a struct named after you app, implement the SwiftUI.App protocol and then let's track the the scene phase of the environment:

// TapMakesCupApp.swift

import Foundation
import SwiftUI

@main
struct TapMakesCupsApp: SwiftUI.App {
    @Environment(\.scenePhase) var scenePhase

    var body: some SwiftUI.Scene {
        WindowGroup {
            ContentView()
                .onChange(of: scenePhase) { newPhase in
                    switch newPhase {
                    case .active:
                        print("App did become active")
                    case .inactive:
                        print("App did become inactive")
                    default:
                        break
                    }
                }
        }
    }
}

Let's also remove the code in ContentView.swift that references the default Experience our project was created with:

// DELETE THESE LINES:

// Load the "Box" scene from the "Experience" Reality File
let boxAnchor = try! Experience.loadBox()

// Add the box anchor to the scene
arView.scene.anchors.append(boxAnchor)

Now we can run the app. There is not much going on right now, since we are just looking at an empty ARView, but notice the app state changes are printed in the console when the app becomes active and when you move the app to the background:

App did become active
App did become inactive

Load 3D assets programmatically from USDZ files #

Since we removed the RealityKit Experience file our template project was created with, we need 3D models to populate our AR experience. You can find a variety of USDZ models available for download in Apple's AR Quick Look gallery. I chose the cup and saucer set for my app. Click any of the models in the gallery to download it.

Create a new group in your Xcode project called Resources and add the USDZ file to the the group. Then create another group called Entities and create a new Swift file within it called CupEntity.swift. Let's also create another group to contain our SwiftUI files: we will call it UI.

We are going to use the Entity.loadAsync type method to load the USDZ file as a RealityKit entity. Entities are holder objects for your RealityKit content. They exist within a RealityKit scene hierarchy, where the Scene object created by ARView is the root object. To load the cup and saucer model we pass the name of the file, without the .usdz extension, to Entity.loadAsync. As long as the USDZ file is included in your application main bundle, the entity method will find the file.

Create a CupEntity struct that inherits from Entity with a static var loadAsync like this:

import Foundation
import Combine
import RealityKit

final class CupEntity: Entity {
    var model: Entity?

    static var loadAsync: AnyPublisher<CupEntity, Error> {
        return Entity.loadAsync(named: "cup_saucer_set")
            .map { loadedCup -> CupEntity in
                let cup = CupEntity()
                loadedCup.name = "Cup"
                cup.model = loadedCup
                return cup
            }
            .eraseToAnyPublisher()
    }
}

We will get a new instance of CupEntity by using the loadAsync static computed property. It will load the cup and saucer file into an entity, which we will store in a CupEntity object that we will publish. This returns a Publisher object from the Combine framework which will inform our subscriber when the cup is loaded.

Pre-load 3D resources #

Let's create another new file in Entities called ResourceLoader.swift. ResourceLoader will be a class responsible for pre-loading our entities, and making them available to our application. We will create a method called loadResources which will return when our 3D assets are loaded. This method returns an AnyCancellable object from Combine so that we can halt the heavy load task if required.

// ResourceLoader.swift

import Foundation
import Combine
import RealityKit

class ResourceLoader {
    typealias LoadCompletion = (Result<CupEntity, Error>) -> Void

    private var loadCancellable: AnyCancellable?
    private var cupEntity: CupEntity?

    func loadResources(completion: @escaping LoadCompletion) -> AnyCancellable? {
        guard let cupEntity else {
            loadCancellable = CupEntity.loadAsync.sink { result in
                if case let .failure(error) = result {
                    print("Failed to load CupEntity: \(error)")
                    completion(.failure(error))
                }
            } receiveValue: { [weak self] cupEntity in
                guard let self else {
                    return
                }
                self.cupEntity = cupEntity
                completion(.success(cupEntity))
            }
            return loadCancellable
        }
        completion(.success(cupEntity))
        return loadCancellable
    }
}

enum ResourceLoaderError: Error {
    case resourceNotLoaded
}

Next, we will create a class called ViewModel to manage our data and inform the UI of changes. ViewModel will be an ObservableObject that will load our assets and publish the state of pre-loading for the UI to observe. Create a new file in UI called ViewModel.swift:

import Foundation
import Combine
import ARKit
import RealityKit

final class ViewModel: NSObject, ObservableObject {
    /// Allow loading to take a minimum amount of time, to ease state transitions
    private static let loadBuffer: TimeInterval = 2

    private let resourceLoader = ResourceLoader()
    private var loadCancellable: AnyCancellable?

    @Published var assetsLoaded = false

    func resume() {
        if !assetsLoaded && loadCancellable == nil {
            loadAssets()
        }
    }

    func pause() {
        loadCancellable?.cancel()
        loadCancellable = nil
    }

    // MARK: - Private methods

    private func loadAssets() {
        let beforeTime = Date().timeIntervalSince1970
        loadCancellable = resourceLoader.loadResources { [weak self] result in
            guard let self else {
                return
            }
            switch result {
            case let .failure(error):
                print("Failed to load assets \(error)")
            case .success:
                let delta = Date().timeIntervalSince1970 - beforeTime
                var buffer = Self.loadBuffer - delta
                if buffer < 0 {
                    buffer = 0
                }
                DispatchQueue.main.asyncAfter(deadline: .now() + buffer) {
                    self.assetsLoaded = true
                }
            }
        }
    }
}

Now we can update our SwiftUI App to assets right away when the app launches. If the app is put into the background, we will cancel loading and begin again once the app comes back into the foreground. Update your app file so it looks like this:

@main
struct TapMakesCupsApp: SwiftUI.App {
    @Environment(\.scenePhase) var scenePhase

    @StateObject var viewModel = ViewModel()

    var body: some SwiftUI.Scene {
        WindowGroup {
            ContentView()
                .environmentObject(viewModel)
                .onChange(of: scenePhase) { newPhase in
                    switch newPhase {
                    case .active:
                        print("App did become active")
                        viewModel.resume()
                    case .inactive:
                        print("App did become inactive")
                        viewModel.pause()
                    default:
                        break
                    }
                }
        }
    }
}

Next, update your ContentView.swift file to include a loading message which will be displayed when the assets have not yet loaded:

import SwiftUI
import RealityKit

struct ContentView : View {
    @EnvironmentObject var viewModel: ViewModel

    var body: some View {
        ZStack {
            // Fullscreen camera ARView
            ARViewContainer().edgesIgnoringSafeArea(.all)

            // Loading screen
            ZStack {
                Color.white
                Text("Loading resources...")
                    .foregroundColor(Color.black)
            }
            .opacity(viewModel.assetsLoaded ? 0 : 1)
            .ignoresSafeArea()
            .animation(Animation.default.speed(1),
                       value: viewModel.assetsLoaded)
        }
    }
}

struct ARViewContainer: UIViewRepresentable {

    func makeUIView(context: Context) -> ARView {
        let arView = ARView(frame: .zero)
        return arView
    }

    func updateUIView(_ uiView: ARView, context: Context) {}

}

#if DEBUG
struct ContentView_Previews : PreviewProvider {
    @StateObject static var viewModel: ViewModel = {
        return ViewModel()
    }()

    static var previews: some View {
        ContentView()
            .environmentObject(viewModel)
    }
}
#endif

Run the app now. The ViewModel will load the resources when it is resumed on the app launch. You will see a loading message which will disappear after the assets are loaded and 2 seconds have elapsed. If you background the app when you first launch it, asset loading will be cancelled and resumed when you bring the app back to the foreground.

Programmatically place content in the real world #

Now it's time for the fun part. First, we need a way to make new cups to place in the world. Open up the ResourceLoader and add a new method called createCup:

func createCup() throws -> Entity {
    guard let cup = cupEntity?.model else {
        throw ResourceLoaderError.resourceNotLoaded
    }
    return cup.clone(recursive: true)
}

The clone method of Entity allows you to create a new copy of an exiting entity, and the recusive option copies all the entities under it in the heirarchy, which we need as well. We use this method to create copies of our cup. We are expecting this method to be called only after pre-loading our assets, so we throw an error if the cup has not been loaded yet. Speaking of which, let's define that error now:

enum ResourceLoaderError: Error {
    case resourceNotLoaded
}

Next, we are going to add code to our ViewModel to manage the state of our cups and ARSession. First, create a dictionary variable to hold on to the anchors that will anchor our cups to the real world:

    private var anchors = [UUID: AnchorEntity]()

Then we can create a new method called addCup to add cups to the scene. It will take 3 arguments:

anchor is the ARAnchor that will anchor the cup to a surface in the real world.
worldTransform is a matrix which describes the position to place the cup in the world.
view is the ARView of our app. We need to pass it to this method to add content to the ARScene.

Create the method like this:

    func addCup(anchor: ARAnchor,
                at worldTransform: simd_float4x4,
                in view: ARView) {
        // Create a new cup to place at the tap location
        let cup: Entity
        do {
            cup = try resourceLoader.createCup()
        } catch let error {
            print("Failed to create cup: \(error)")
            return
        }

        defer {
            // Get translation from transform
            let column = worldTransform.columns.3
            let translation = SIMD3<Float>(column.x, column.y, column.z)

            // Move the cup to the tap location
            cup.setPosition(translation, relativeTo: nil)
        }

        // If there is not already an anchor here, create one
        guard let anchorEntity = anchors[anchor.identifier] else {
            let anchorEntity = AnchorEntity(anchor: anchor)
            anchorEntity.addChild(cup)
            view.scene.addAnchor(anchorEntity)
            anchors[anchor.identifier] = anchorEntity
            return
        }

        // Add the cup to the existing anchor
        anchorEntity.addChild(cup)
    }

For each anchor that we wish to attach content to, we need an AnchorEntity which will act as the parent for our cup entities and tether them to the real world. If we don't have an AnchorEntity for the anchor we are interested in, we create one. We create a new cup and add it as a child of our anchor entity.

Finally, in the defer block, we set the position of the cup to the desired real world position. The transform includes a size, position and orientation, but since we are only interested in the position we get the translation from the transform and apply it to the cup with setPosition.

There is one more thing we have to do before we can place cups in the real world.

Configure ARSession #

We want to place cups on horizontal surfaces in the real world. To do this, we will configure our ARSession for horizontal plane detection. Create a new method in ViewModel called configureSession:

func configureSession(forView arView: ARView) {
    let config = ARWorldTrackingConfiguration()
    config.planeDetection = [.horizontal]
    arView.session.run(config)
    arView.session.delegate = self
}

Now horizontal surfaces will be automatically detected for our ARSession. Additionally, we set the ViewModel as the delegate for our session. It will be informed of updates to our anchors. We are going to conform to the ARSessionDelegate and implement a method to be informed when anchors are no longer detected and removed, so we can removed the orphaned cups associated with them:

// MARK: - ARSessionDelegate

extension ViewModel: ARSessionDelegate {
    func session(_ session: ARSession, didRemove anchors: [ARAnchor]) {
        anchors.forEach { anchor in
            guard let anchorEntity = self.anchors[anchor.identifier] else {
                return
            }
            // Lost an anchor, remove the AnchorEntity from the Scene
            anchorEntity.scene?.removeAnchor(anchorEntity)
            self.anchors.removeValue(forKey: anchor.identifier)
        }
    }
}

Good, now we can keep track of only the anchors that are holding cups in the real world. Let's finish this app so we can see our AR content in action!

Translate tap locations into real world positions #

Open up ContentView.swift. Edit ARViewContainer so that it looks like this:

struct ARViewContainer: UIViewRepresentable {
    @EnvironmentObject var viewModel: ViewModel

    func makeUIView(context: Context) -> ARView {
        let arView = ARView(frame: .zero)

        // Configure the session
        viewModel.configureSession(forView: arView)

        // Capture taps into the ARView
        context.coordinator.arView = arView
        let tapRecognizer = UITapGestureRecognizer(target: context.coordinator,
                                                   action: #selector(Coordinator.viewTapped(_:)))
        tapRecognizer.name = "ARView Tap"
        arView.addGestureRecognizer(tapRecognizer)

        return arView
    }

    func updateUIView(_ uiView: ARView, context: Context) {}

    class Coordinator: NSObject {
        weak var arView: ARView?
        let parent: ARViewContainer

        init(parent: ARViewContainer) {
            self.parent = parent
        }

        @objc func viewTapped(_ gesture: UITapGestureRecognizer) {
            let point = gesture.location(in: gesture.view)
            guard let arView,
                  let result = arView.raycast(from: point,
                                              allowing: .existingPlaneGeometry,
                                              alignment: .horizontal).first,
                  let anchor = result.anchor
            else {
                return
            }
            parent.viewModel.addCup(anchor: anchor,
                                    at: result.worldTransform,
                                    in: arView)
        }
    }

    func makeCoordinator() -> ARViewContainer.Coordinator {
        return Coordinator(parent: self)
    }
}

This will configure our ARSession when it is created. Taps on the view will be captured. We can use the touch point in our ARView to project a ray that will intersect with detected horizontal planes. The first result will be the first plane intersected by that ray, this is the location where we want to place our cup. We pass the anchor for the intersected plane and the transform of the intersection to ViewModel.addCup.

Run the app! When you tap on detected horizontal planes, it will place a cup there. If you want more help visualizing anchors and detected planes, you can add debug options to the ARView:

// debug options are powerful tools for understanding RealityKit
arView.debugOptions = [
    .showAnchorOrigins,
    .showAnchorGeometry
]

Complete project #

The complete TapMakesCup cap is available as a guide and starting app template on my GitHub here.

How to choose an anchor for your RealityKit iOS AR app

2023-01-15T00:00:00Z

If you are like me, you created a RealityKit AR app using the Xcode template Augmented Reality App under New Project. This template project includes a basic Reality Composer Experience.rcproject file which is loaded into the app and added to the Scene's anchors. This will anchor the scene to the first horizontal surface that is found. I wanted to know how to choose which surface my scene would be anchored to, and this blog post will explain how I did it, as well as discussing the details of anchoring virtual content to the real world.

ARAnchors and AnchorEntities #

No one can be told what The Matrix is, you have to see it for yourself. To easily visualize and understand anchors, add the following debug options to your ARView and run the app:

let config = ARWorldTrackingConfiguration()
config.planeDetection = [.horizontal, .vertical]
arView.session.run(config)

// debug options are powerful tools for understanding RealityKit
arView.debugOptions = [
    .showAnchorOrigins,
    .showAnchorGeometry
]

The template augmented reality project in Xcode loads an AnchorEntity for your scene, and adds it to the Scene's anchors collection:

// Load the "Box" scene from the "Experience" Reality File
let boxAnchor = try! Experience.loadBox()

// Add the box anchor to the scene
arView.scene.anchors.append(boxAnchor)

An AnchorEntity is used to attach virtual content to the real world. It is an Entity which extists in the hierarchy of your Scene, usually as a direct child of the Scene, meaning that your content will exist as children or descendents of your anchor entity.

An AnchorEntity anchors itself to the real world using something called an ARAnchor. An ARAnchor is a fixed place within the real world you can attach content to, such as a hoziontal surface like a table. An AnchorEntity is created with a target describing the type of ARAnchor it is looking to attach to:

// Attach to any horizonal surface of any size
let anchorEntity = AnchorEntity(.plane(.horizontal, classification: .any, minimumBounds: SIMD2(repeating: 0)))

// Attach to a horizonal floor surface with at least 1m square bounds
let anchorEntity = AnchorEntity(.plane(.horizontal, classification: .floor, minimumBounds: SIMD2(repeating: 1)))

// Attach to a person's body
let anchorEntity = AnchorEntity(.body)

By default, the reality file scene is looking for a horizontal anchor. It will attach itself to the first anchor it finds, but that may not be what you want. Maybe you want to be able to pick which surface your scene will attach to. In order to do this, you will need to look for an anchor and attach your scene to it.

ARSessionDelegate #

You can know about when ARAnchors are found by setting a delegate on your ARSession and implementing the ARSessionDelegate protocol methods.

First, configure your ARSession for world tracking, using the ARWorldTrackingConfiguration. We will use plane detection to find horizontal planes, suitable for placing our scene:

    let config = ARWorldTrackingConfiguration()
    config.planeDetection = [.horizontal]
    arView.session.run(config)

Now, any detected horizontal planes will be delivered to your ARSessionDelegate methods:

// MARK: - ARSessionDelegate

extension MySceneManager: ARSessionDelegate {
    func session(_ session: ARSession, didAdd anchors: [ARAnchor]) {
        for anchor in anchors {
            guard let plane = anchor as? ARPlaneAnchor,
                  plane.alignment == .horizontal else {
                continue
            }
            print("Found horizontal plane \(plane)")
        }
    }

    func session(_ session: ARSession, didUpdate anchors: [ARAnchor]) {
        for anchor in anchors {
            guard let plane = anchor as? ARPlaneAnchor,
                  plane.alignment == .horizontal else {
                continue
            }
            print("Updated horizontal plane \(plane)")
        }
    }

    func session(_ session: ARSession, didRemove anchors: [ARAnchor]) {
        for anchor in anchors {
            guard let plane = anchor as? ARPlaneAnchor,
                  plane.alignment == .horizontal else {
                continue
            }
            print("Lost horizontal plane \(plane)")
        }
    }
}

Anchoring your scene #

Now that you can find anchors, you have many options to place your scene. You can look at the qualities of the anchors, and decide which one to attach your scene to, or you could have some kind of user input guide the placement of your AR content in the real world.

When you are ready to attach your content to an anchor, you can create a new AnchorEntity using that anchor. You can then simply add your loaded Reality Composer scene as a child of that anchor entity. Remember that an AnchorEntity is just an Entity. It doesn't have to be anchored itself, it can simply be the child of another entity, like the anchor entity you create yourself:

let boxAnchor = try! Experience.loadBox()
let myAnchorEntity = AnchorEntity(anchor: anchor)
myAnchorEntity.addChild(boxAnchor)

Tap to place your scene #

An easy way to select an anchor for your scene is to allow the user to tap the view, and then select the first horizontal plane hit by a raycast projected from the camera to place our scene:

// Capture taps to place the scene
let recognizer = UITapGestureRecognizer(target: self,
                                        action: #selector(self.viewTapped(_:)))
arView.addGestureRecognizer(recognizer)

// . . .

@objc private func viewTapped(_ recognizer: UITapGestureRecognizer) {
    guard !arView.manager.sceneAttached else {
        return
    }
    let point = recognizer.location(in: arView)
    guard let anchor = arView.raycast(from: point,
                                      allowing: .existingPlaneInfinite,
                                      alignment: .horizontal).first?.anchor else {
        return
    }
    // Use the planar surface found to anchor your scene
}

Putting it all together #

All of the concepts discussed in this guide are demonstrated in a repo available on my GitHub.

Apple's augmented reality modules are still very new, and not widely used within the app ecosystem yet. This means that guides and documentation can be difficult to find. Apple does have some nice help available scattered throughout the documentation, but it can be difficult to approach for the first time. When working with augmented reality, you should prepare yourself to dig deeply within the documentation, read the public APIs available for each class and accept that you will slowly come to understand how to use Apple's AR.

You Should Be Using Cloudflare For Your Website

2022-09-13T00:00:00Z

Cloudflare provides a free service that will speed up your website, protect you from attacks and provide analytics all for free and with an incredibly fast and easy setup; if you have a small or personal website you should be using Cloudflare. Cloudflare will give you an SSL certificate so your website can provide HTTPS, a CDN network that will cache your website around the world and deliver content to your users closest to their location (faster than your server), they will manage your DNS and improve lookup time (further speeding up your users experience), they will provide you with analytics for free and without having to add any Google or other <script> tags to your code. I might be only scratching the surface of what Cloudflare can do and I might be late to the party, but let me explain how Cloudflare has helped me.

Cloudflare Provides An SSL Certificate #

Your users need to be able to connect to your site using HTTPS. They will not trust your site with a giant red 🔓 icon next to your URL. HTTPS requires an SSL certiciate, which can be complicated to obtain and setup, but Cloudflare provides and incredibly simple process to get a valid SSL certificate for your site as well as giving easy instructions with clear documentation to get you setup in no time.

For me, this was my first time setting up SSL myself, and using Cloudflare meant I had one less things to worry about when I wanted to deploy my website.

Cloudflare Provides DNS Management, a CDN and Caches Your Website #

When you setup Cloudflare, you transfer your nameservers from your domain registrars nameservers to Cloudflares. This means that Cloudflare provides your DNS management. I found Cloudflares DNS management to be simpler and more intuitive than my domain registrar, GoDaddy, and additionally, Cloudflare will proxy your DNS queries which will speedup your site's lookup time and also protect your server by masking your IP.

Cloudflare also operates as a CDN and caches your site's assets. I am hosting my site on Linodes cheapest shared server plan, including my personal blog, the Daily Fat Counter app website and Satle which gets hundreds of visitors per day. Cloudflare serves most requests from the cache, and so the load on my server is reduced by 3 times or more. This is incredibly useful for anyone with a small website and low-cost hosting.

Cloudflare Provides Detailed Analytics For Free Without Any Setup #

When you use Cloudflare to manage your DNS, as a bonus you get detailed analytics for your site including your daily/weekly/monthly unique visitos, total requests, country demographics and many more incredibly useful statistics for your website. For me, all I require for my site is basic analytics so I can see how much traffic the site is getting, and where it is coming from, so I don't need to install Google Analytics just for this purpose.

Cloudflare Automatically Protects Your Website From Most Attacks #

If you are like me, then you don't have experience mitigating attacks against your website, nor do you have the knowledge to easily identify and block them. Cloudflare automatically protects your website from many common attacks that could be made against your website. DNS proxy and CDN cacheing both help defend your server from being overloaded and brought down.

According to Cloudflare, 7 attacks against my site were blocked in the past month. Nice! 👍

Cloudflare Optimizes Your Code For You #

Another free and automatic service provided by Cloudflare, if you choose to enable it, is optimization and minification of your code. Cloudflare takes your HTML, CSS and JavaScript assets and will serve optimized versions of them automatically for you, and update them whenever you update your source code. This is just another way that Cloudflare saves you bandwidth and improves load times for your users.

Cloudflare is Free, Easy and Just Awesome #

The amount of value Cloudflare is offering for free is insane, and the fact that it requires almost no commitment from you makes it, in my opinion, an obvious choice to use. This is not like a service like Firebase that requires itself to be embedded in your product, so that when your product takes off you will be charged a lot and it won't be easy to remove. Cloudflare offers a simple service that is easy to setup and anytime you want you could easy just move your nameservers back to your registrar and leave Cloudflare behind, but why would you?

What I Learned Publishing My First App

2022-09-10T00:00:00Z

As a mobile developer, I have built many apps as side projects in my spare time. These are usually for the purpose of learning some new peice of technology, or prototyping some quick idea I had in my head, but somehow I've gone my entire career without publishing an app that I owned. I decided recently that should change, so I developed and published by first app under my name to the Apple App Store and Google Play Store, Daily Fat Counter.

There were many considerations to account for and tasks to accomplish beyond just developing the app, so here are a list of them that may be helpful for you when you decided to publish your first app.

Consider creating accounts for your developer self. #

You will need to provide contact information in various places and to various parties in the process of publishing your app. It will be in your Apple and Google Developer accounts, your contact information for your app listing, required for feedback during testing and others. In my case, I ended up using personal emails for these, however it is probably a good idea to setup an email account for use with your development work. That way you can publish these contact details widely without mixing your personal contacts with your development work.

You need a developer account. #

The Apple Developer Program and Google Play Developer Accounts both require paying a fee. For Apple, this is $99USD yearly, and for Google it is a one-time fee of $25USD. Be careful with your Google Developer Account. If you don't use it after 1 year it will be expired permenantly and you will not be refunded. This happened to me because I signed up for the program with the intention to publish an app, but it took me much longer than I expected.

You should create your account early, since it will require some identity verification that will take some time before you will be able to publish any apps. There are also likely a few forms you will have to fill out for legal and tax purposes, so be prepared to spend some time reading and familiarizing yourself with them.

What OS Versions Should I Support? #

When building side projects for learning and fun, it is easy to simply develop only against whatever device you are planning to use to run your app. When you consider releasing your app in the wild, however, you suddenly must concern yourself with supporting a wide variety of devices.

The two main considerations when deciding what OS versions to support are what operating systems the ideal users of your app are using, and the amount of development effort required to support each version. For Daily Fat Counter, I wanted the app to be accessible to many people and the app is also small and not very complex, so the effort to support a wide array of operating systems is minimal and the payoff for doing so is well worth it.

On iOS I developed the entire app against iOS 15, which was preselected as the latest major iOS version. I was having fun learning Swift UI, and I was mainly considering my wife as the sole user. When it came time for release though, I decided to support back to iOS 14.0 so I could wouldn't leave out too many users on launch. There was a bit of effort to refactor the code to be compatible with 14.0, so it would have been a good idea to develop against this version from the start.

Considering Android, the backwards compatibility is quite good, especially with the Jetpack components. I ended up supporting all the way back to Android 5.1 (API 22) which covers 98% of devices according to Google. For a small app without a lot of complexity like Daily Fat Counter this turned out to be very easy. There is only one place where the code is different before Android 8.0, and that is concerning the datetime libraries.

You need an app icon. #

I'm an amateur graphic designer at best, so for my app icon I got creative and ended up using code to create it. I wrote a whole blog post about it, in case you want to try this yourself. Alternatively, there are free programs like GIMP which you can use to easily make a basic app icon. Be creative and don't fuss too much over it. The important thing is to make it simple and eye catching.

You need screenshots. #

The worst thing you could do for your app listing is to simply screenshot the app and post the minimum number of those images directly into your listing. You must at least put in the effort to show your screenshot running in a device frame, with some text describing the functionality of your app. For me, since I'm an amateur graphic designer, I ended up using a free Sketch template that I found using a Google search like: "Sketch template app store screenshots." I found one that was suitable for my purpose, and I used it to create 40 screenshots (10 per device size factor and 2 size factors per platform) as well as using it to learn how to create and modify such a template in Sketch. Those same skills will be useful even in other design programs, and it was a great opportunity to learn more by following the example of others. This is always how I learn best.

This is the point in development when I decided not to support tablets. I realized that I had not put effort into making my UI appealing on large-form devices, and I was unwilling to show that UI in a screenshot. In the future, if I decide large-form device support is important, I will take the time to create a beautiful UI for those devices and spend the time to craft enticing screenshots for tablets.

You need a website. #

This was something I did not consider during development of my app, and it only hit me once I started putting together my app listing on Apple and Google for publishing. I put together a basic page with a description of the app, a screenshot and a link to the App Store and Play Store listings. I used already use Linode for hosting my personal blog, so I created a subdomain for my app and hosted it there. To supply an SSL certificate to enable HTTPS I used Cloudflare. I needed a website for 3 main reasons:

There is a URL field in your app listing that will be shown to users browsing the App Store or Play Store.
You need a place for your users to submit feedback during testing.
A privacy policy for your app must be hosted somewhere so it can be linked to in your app listing.

Speaking of privacy policies...

You need a privacy policy. #

The Apple App Store and Google Play Console both require you to declare and describe what user data your app collects and transmits to your backend. In order to comply with this declaration, a privacy policy is required. It is worth considering early on what user data your app will collect. This can easily affect you simply by inlcuding an analytics library such as Google Analytics. Consider all the third party libraries you include as well as any data which is persisted by your app.

For Daily Fat Counter, this was relatively simple. The app does not transmit any user data, and the only data which is collected is the daily fat records the user creates which is kept on device and able to be deleted at any time. The privacy policy simply states this.

Plan to spend a good amount of time on your app listing. #

Your app store listing can contain a lot of information, and it is prudent for you to invest a good amount of time working on your app's title, description and metadata. As a side-project, Daily Fat Counter will not be heavily promoted, and so one of the only ways for people to know about it will be through the app listing. You will want to consider how to use your title and subtitle to describe your app in short and semi-short terms. Your description can be quite long, and it is a good opportunity for you to go in depth about your application and how user's can benefit from it. It may also not be immediately obvious which category your app fits into, so spend some time browsing through categories you think may be applicable to your app and see which category has apps that are the most similar to yours.

There are many great articles regarding app store optimization (ASO) and a quick Google search should give you many ideas and insights about how to tailor your app listing for optimal visibility.

Organic growth is not dead. #

I developed Daily Fat Counter for my wife. She was required to be on a fat-restricted diet, meaning she had to track the grams of dietary fat she consumed throughout each day. Daily Fat Counter helps users track the amount of fat they consume each day, as well as see a history of their fat consumption in relation to their goal. My ideal user story was Danielle's, and so it made the app easy to design as well as gave it a clear goal for success. If it is useful to her then it is a success.

Now, if it can be useful to her, then surely there must be more people in the world like her who could benefit from it. If just one more person downloads and uses Daily Fat Counter, then it's impact has been doubled. That is how I define success for the app. I maintain a developer account already so I can publish other apps, and I maintain my website already in order to publish my blog, so Daily Fat Counter doesn't cost me anything beyond the occasional bit of development time to maintain it and update it for newer OS versions (a non-trivial bit of effort.)

As far as the apps performance, though, it has garnered over 1000 impressions on the Apple App Store, resulting in over 100 installs, just over 2 months after release. On Google, the app has received about 300 impressions, resulting in 25 aquisitions in the same time, and it reports 9 active devices at present. I am very happy with these results. I have not done any paid promotion, or even any promotion at all of this app, beyond telling my wife that it's done and she can install it.

To me, each person that is positively impacted by the app is a blessing and I am grateful for each of them.

Many people in the world can benefit from your unique gifts and your time on this earth. The thing I learned most from publishing my first app is that your time is valuable, and if you spend it all working on projects that only you ever see because you never publish them, then you've done a nice thing for yourself but no one else can benefit from what you've done.

If you are making something that is useful to you, then it will be useful to someone else, so share it with the world and let others benefit from your creations.

Make an App Icon With Swift UI

2022-06-26T00:00:00Z

It's very easy to create an app icon for your iOS app using Swift UI, but this process is not a native part of Apple development and you will need to use a few tricks to get image assets that can be used for you Xcode project and the App Store.

Why use Swift UI to create your app icon #

As a developer, I have been getting joy from learning Swift UI and trying out a new framework. I have been developing my app, Paraideas, exclusively in Swift UI and I created some nice custom view components that look beautiful on the iPhone. When I started thinking about the app icon I was inspired by the UI I was working on, and I started searching for a way to create an app icon using Swift UI. I was unable to find a concise and complete guide, so I developed this one.

Create a Swift UI view for an app icon #

We want the reference image for our app icon to be a square 1024x1024 pixels. We will first setup our preview to display a surface of an appropriate size for use to draw our app icon.

Create a new Swift UI view file to serve as your app icon. I've called mine AppIcon. Since I will be using an iPad Pro (12.9-inch) (5th generation) to render the icon for screenshotting, which is a retina 2x device, I will be using a point size of 512 for my icon size. We will setup a preview to display the Swift UI view at an appropriate size.

import SwiftUI

struct AppIcon: View {
  static let appIconSize: CGFloat = 512

  var body: some View {
    Text("Hello, World!")
  }
}

struct AppIcon_Previews: PreviewProvider {
  static var previews: some View {
    AppIcon()
      .previewLayout(.fixed(width: AppIcon.appIconSize,
                            height: AppIcon.appIconSize))
  }
}

Draw the icon #

Swift UI offers a number of tools for creating interesting icons, including shapes, colour gradients and visual effects like shadows and blur. Using the tools of the Swift UI framework it's possible to create a huge variety of icons. Remember, your code does not have to be performant. This view is not designed to be rendered anywhere in your app, but rather it will be built once during development to create an image asset for your icon.

For this tutorial I will be creating an icon for my app designed to spark creativity. Since this is an app about inspriring thoughts, I will make the icon a cartoon-style thought bubble.

I started with a ZStack so I can have elements placed on top of each other, and I set the frame to be the size of the app icon. The background is a gradient that forms a "sky" and the thought bubble is created using Swift UI Circles stacked on top of each other. I created this in less than half an hour, and I'm sure with more creativity and time you will create some amazing app icons.

import SwiftUI

struct AppIcon: View {
    static let appIconSize: CGFloat = 512

    private let cloudBubbleSize: CGFloat = 60

    var body: some View {
        ZStack {
            // Sky blue background
            LinearGradient(colors: [Color("LightSky"),
                                    Color("SkyBlue")],
                           startPoint: .topTrailing,
                           endPoint: .bottomLeading)

            // Leading bubbles
            Circle()
                .path(in: CGRect(origin: CGPoint(x: 20,
                                                 y: AppIcon.appIconSize - cloudBubbleSize - 20),
                                 size: CGSize(width: cloudBubbleSize * 0.5,
                                              height: cloudBubbleSize * 0.5)))
                .fill(Color("White"))
                .shadow(color: Color.black.opacity(0.4), radius: 5, x: 5, y: 5)
            Circle()
                .path(in: CGRect(origin: CGPoint(x: 30,
                                                 y: AppIcon.appIconSize - cloudBubbleSize - 70),
                                 size: CGSize(width: cloudBubbleSize * 0.7,
                                              height: cloudBubbleSize * 0.7)))
                .fill(Color("White"))
                .shadow(color: Color.black.opacity(0.4), radius: 5, x: 5, y: 5)
            Circle()
                .path(in: CGRect(origin: CGPoint(x: 50, y: AppIcon.appIconSize - cloudBubbleSize - 140),
                                 size: CGSize(width: cloudBubbleSize,
                                              height: cloudBubbleSize)))
                .fill(Color("White"))
                .shadow(color: Color.black.opacity(0.4), radius: 5, x: 5, y: 5)

            // Cloud bubbles
            ZStack {
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 200, y: 200),
                                     size: CGSize(width: cloudBubbleSize * 3,
                                                  height: cloudBubbleSize * 3)))
                    .fill(Color("White"))
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 100, y: 180),
                                     size: CGSize(width: cloudBubbleSize * 2.8,
                                                  height: cloudBubbleSize * 2.8)))
                    .fill(Color("White"))
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 20, y: 100),
                                     size: CGSize(width: cloudBubbleSize * 2.5,
                                                  height: cloudBubbleSize * 2.5)))
                    .fill(Color("White"))
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 100, y: 30),
                                     size: CGSize(width: cloudBubbleSize * 3.5,
                                                  height: cloudBubbleSize * 3.5)))
                    .fill(Color("White"))
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 330, y: 180),
                                     size: CGSize(width: cloudBubbleSize * 2.2,
                                                  height: cloudBubbleSize * 2.2)))
                    .fill(Color("White"))
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 250, y: 50),
                                     size: CGSize(width: cloudBubbleSize * 2.8,
                                                  height: cloudBubbleSize * 2.8)))
                    .fill(Color("White"))
                Circle()
                    .path(in: CGRect(origin: CGPoint(x: 360, y: 90),
                                     size: CGSize(width: cloudBubbleSize * 2,
                                                  height: cloudBubbleSize * 2)))
                    .fill(Color("White"))
            }
            .compositingGroup()
            .shadow(color: Color.black.opacity(0.4), radius: 5, x: 5, y: 5)
        }.frame(width: AppIcon.appIconSize, height: AppIcon.appIconSize)
    }
}

struct AppIcon_Previews: PreviewProvider {
    static var previews: some View {
        AppIcon()
            .previewLayout(.fixed(width: AppIcon.appIconSize,
                                  height: AppIcon.appIconSize))
    }
}

Create the reference icon image #

Now that we have our icon designed in Swift UI, we need to create an image asset which can be sized appropriately for our icons. At the time of writing, running a live preview in Xcode will not provide a surface with the fixed width and height layout we have set, so we will need to run this on an iPad simulator.

Modify your Swift UI app to simply display only your app icon and run your app on the iPad Pro simulator. I am running on an iPad so I have a display big enough to fit the entire app icon on the screen. Once the app is running and you can see your app icon displayed on the screen, take a screenshot of the simulator.

Open the screenshot in Preview, toggle edit mode and use the rectangle select to draw a rectangle over your app icon. You can zoom in to a very high value in preview to line up the rectangle with the corners of your app icon. The rectangle select should display a value of 1024x1024 when selected. Now you can use the "Crop to Selection" command to trim the images to exactly 1024x1024 pixels and save the image. Congratulations! You have the reference image for your app icon.

Resize the reference image to required icon sizes #

Once you have your 1024*1024 image, you can down resize it down to all the various sizes you will need for Xcode and the App Store. For me, I was lazy so I used this App Icon Generator which I found by doing a search for "app icon generator". You can easily resize the image yourself in Photoshop, Sketch, Gimp and many other programs.

To create an Android app icon you can simply use the image asset creation tool in Android Studio, select your image and let the masks apply to the reference. When designing for Android though you may want to create a foreground layer and background layer. This is out of the scope of this guide.

Add your new app icon to your Xcode project #

Your done! You have your app icon image set, so you can drag it into your xcassets in Xcode to add your icon to your project. Don't forget to undo the change you made to your Swift UI app so your app icon is not displayed. You can save the app icon Swift UI file in your project so you can modify or reuse it in the future.

Creating a Swift UI app icon is a great option for someone who is a developer first and graphic designer second, or someone with limited experience with graphic design software. My hope is that someday soon Apple will provide greater support for creating app icons in Swift UI, and maybe make it a native feature of the platform.

Functions: Why Smaller is Not Always Better

2022-01-24T00:00:00Z

Throughout my career as a software engineer, I have come across many simple heuristics that developers use to guide their design decisions and inform their coding style. One such rule-of-thumb I have heard quoted is that "small functions are better". Those following this rule-of-thumb assert that writing small functions enforces good coding principals and makes for better software. While I would like my functions to be no larger than they need to be, I find the "small functions are better" rule tends to create more problems than it solves.

Within Robert C. Martin's seminal work Clean Code, chapter 3 is dedicated to discussing the principals of clean code in relation to functions. Martin references the "small functions are better" rule within the chapter, and uses it, among other techniques, to refactor a function which is an example of code that could be cleaner. The function is as follows:

The function to be refactored (Listing 3-1) #

HtmlUtil.java

public static String testableHtml(
        PageData pageData,
        boolean includeSuiteSetup
) throws Exception {
    WikiPage wikiPage = pageData.getWikiPage();
    StringBuffer buffer = new StringBuffer();
    if (pageData.hasAttribute("Test")) {
        if (includeSuiteSetup) {
            WikiPage suiteSetup =
                    PageCrawlerImpl.getInheritedPage(
                            SuiteResponder.SUITE_SETUP_NAME, wikiPage
                    );
            if (suiteSetup != null) {
                WikiPagePath pagePath =
                        suiteSetup.getPageCrawler().getFullPath(suiteSetup);
                String pagePathName = PathParser.render(pagePath);
                buffer.append("!include -setup .")
                        .append(pagePathName)
                        .append("\n");
            }
        }
        WikiPage setup =
                PageCrawlerImpl.getInheritedPage("SetUp", wikiPage);
        if (setup != null) {
            WikiPagePath setupPath =
                    wikiPage.getPageCrawler().getFullPath(setup);
            String setupPathName = PathParser.render(setupPath);
            buffer.append("!include -setup .")
                    .append(setupPathName)
                    .append("\n");
        }
    }
    buffer.append(pageData.getContent());
    if (pageData.hasAttribute("Test")) {
        WikiPage teardown =
                PageCrawlerImpl.getInheritedPage("TearDown", wikiPage);
        if (teardown != null) {
            WikiPagePath tearDownPath =
                    wikiPage.getPageCrawler().getFullPath(teardown);
            String tearDownPathName = PathParser.render(tearDownPath);
            buffer.append("\n")
                    .append("!include -teardown .")
                    .append(tearDownPathName)
                    .append("\n");
        }
        if (includeSuiteSetup) {
            WikiPage suiteTeardown =
                    PageCrawlerImpl.getInheritedPage(
                            SuiteResponder.SUITE_TEARDOWN_NAME,
                            wikiPage
                    );
            if (suiteTeardown != null) {
                WikiPagePath pagePath =
                        suiteTeardown.getPageCrawler().getFullPath (suiteTeardown);
                String pagePathName = PathParser.render(pagePath);
                buffer.append("!include -teardown .")
                        .append(pagePathName)
                        .append("\n");
            }
        }
    }
    pageData.setContent(buffer.toString());
    return pageData.getHtml();
}

My first and most immediate problem with the above code is the control flow resulting in many branching blocks which may or may not be executed during the course of this function. We end up with blocks which are nested many levels deep. This makes the function difficult to read since I have to keep track of which block of control flow I am in at a time, but more importantly, it is hard for me to keep the exponentially increasing paths through the logic in my head at once. Crucially, this function is also difficult to test, because it requires an exponentially increasing set of test cases in order to cover all of the possible branches.

The above function is not "bad" code. It does a good job of hiding away the implementation details of the task to render some HTML from the page data which is passed in as an argument. Some one line comments throughout the function describing what each step does would do a lot of work to make this function more readable and comprehensible.

It is an error to believe that all the problems of control flow required for branching logic can be solved by clean code. The fact is if your application requires branching logic, then your implementation will require some form of control flow and you can't get around that. How well your implementation is able to be comprehended and tested is what matters.

Martin eventually refactors the function using the principals of clean code, which results in a class with a static render function:

Matin's refactor according to the principals of clean code (Listing 3-7) #

SetupTeardownIncluder.java

package fitnesse.html;
import fitnesse.responders.run.SuiteResponder;
import fitnesse.wiki.*;

public class SetupTeardownIncluder {
    private PageData pageData;
    private boolean isSuite;
    private WikiPage testPage;
    private StringBuffer newPageContent;
    private PageCrawler pageCrawler;
    public static String render(PageData pageData) throws Exception {
        return render(pageData, false);
    }
    public static String render(PageData pageData, boolean isSuite)
            throws Exception {
        return new SetupTeardownIncluder(pageData).render(isSuite);
    }
    private SetupTeardownIncluder(PageData pageData) {
        this.pageData = pageData;
        testPage = pageData.getWikiPage();
        pageCrawler = testPage.getPageCrawler();
        newPageContent = new StringBuffer();
    }
    private String render(boolean isSuite) throws Exception {
        this.isSuite = isSuite;
        if (isTestPage())
            includeSetupAndTeardownPages();
        return pageData.getHtml();
    }
    private boolean isTestPage() throws Exception {
        return pageData.hasAttribute("Test");
    }
    private void includeSetupAndTeardownPages() throws Exception {
        includeSetupPages();
        includePageContent();
        includeTeardownPages();
        updatePageContent();
    }
    private void includeSetupPages() throws Exception {
        if (isSuite)
            includeSuiteSetupPage();
        includeSetupPage();
    }
    private void includeSuiteSetupPage() throws Exception {
        include(SuiteResponder.SUITE_SETUP_NAME, "-setup");
    }
    private void includeSetupPage() throws Exception {
        include("SetUp", "-setup");
    }
    private void includePageContent() throws Exception {
        newPageContent.append(pageData.getContent());
    }
    private void includeTeardownPages() throws Exception {
        includeTeardownPage();
        if (isSuite)
            includeSuiteTeardownPage();
    }
    private void includeTeardownPage() throws Exception {
        include("TearDown", "-teardown");
    }
    private void includeSuiteTeardownPage() throws Exception {
        include(SuiteResponder.SUITE_TEARDOWN_NAME, "-teardown");
    }
    private void updatePageContent() throws Exception {
        pageData.setContent(newPageContent.toString());
    }
    private void include(String pageName, String arg) throws Exception {
        WikiPage inheritedPage = findInheritedPage(pageName);
        if (inheritedPage != null) {
            String pagePathName = getPathNameForPage(inheritedPage);
            buildIncludeDirective(pagePathName, arg);
        }
    }
    private WikiPage findInheritedPage(String pageName) throws Exception {
        return PageCrawlerImpl.getInheritedPage(pageName, testPage);
    }
    private String getPathNameForPage(WikiPage page) throws Exception {
        WikiPagePath pagePath = pageCrawler.getFullPath(page);
        return PathParser.render(pagePath);
    }
    private void buildIncludeDirective(String pagePathName, String arg) {
        newPageContent
                .append("\n!include ")
                .append(arg)
                .append(" .")
                .append(pagePathName)
                .append("\n");
    }
}

Martin says that "the first rule of functions is that they should be small." The heuristic seems to follow from the principals that functions should do one thing, not have side-effects and not mix levels of abstraction. While I agree with all of these principals, all can be adhered to without strictly sticking to a certain function size. Martin even goes so far as to suggest an upper limit of 20 lines.

A function should be as large as it needs to be in order to fulfill it's obligation. Functions can nicely hide away the implementation details of a single task, which may be numerous or cumbersome. As long as you are mostly just invoking the function, rather than operating on it's internals, why would it matter how large the function is? I would rather not look at the body of the function at all! Rather the function name and it's context in the code should cleanly express it's purpose. Further, if the function is well designed and written in the first place, then it's internals should not need much modification in the future.

The problems that I observe when developers religiously stick to the "smaller is better" rule are:

lots of small functions lead to deep call stacks,
implementation details get hidden in functions which are only called from one place,
and functions become redundent wrappers for other function calls.

Let's discuss each of these points in relation to the above code (Listing 3-7) and refactor it again to be even cleaner.

Lots of small functions lead to deep call stacks #

When we take a large function and refactor it into many smaller functions, we often do it in a way where those smaller functions become nested within each other. The problem this leads to is that the smaller, deeply-nested functions are only called within the context of a call stack many levels deep.

Let's say I have never seen this code before, but I am tasked with changing something in the buildIncludeDirective function. In order to understand the context the function is called within I go back through the call stack, and I have to unnest each layer of it and understand them individually, in order to piece together what this function does in context. The call stack may end up looking like this:

SetupTeardownIncluder.render(PageData)
  SetupTeardownIncluder.render(PageData,boolean)
    SetupTeardownIncluder.render(boolean)
      SetupTeardownIncluder.includeSetupAndTeardownPages()
        SetupTeardownIncluder.includeSetupPages()
          SetupTeardownIncluder.includeSuiteSetupPage()
            SetupTeardownIncluder.include(String,String)
              SetupTeardownIncluder.buildIncludeDirective(String,String)

While breaking the original testableHtml (Listing 3-1) function into many smaller pieces does clean it up, it introduces the problem of deep call stacks that are difficult and time consuming to trace through. The problem is amplified in larger projects where the call stacks may be much deeper, and spread out across multiple classes or even packages.

Implementation details get hidden in functions which are only called from one place #

While separating levels of abstraction is a useful principle that does help the original monolithic testableHtml function become cleaner, the refactor introduces a new problem. The buildIncludeDirective function is only called from include. It is not reused anywhere else and so it should just be a part of the include function. Indeed it is just a part of the include function, but the implementation details are hidden away from include so that you have to look a level deeper to understand what include actually does.

private void include(String pageName, String arg) throws Exception {
    WikiPage inheritedPage = findInheritedPage(pageName);
    if (inheritedPage != null) {
        String pagePathName = getPathNameForPage(inheritedPage);
        buildIncludeDirective(pagePathName, arg);
    }
}

// . . .

private void buildIncludeDirective(String pagePathName, String arg) {
    newPageContent
            .append("\n!include ")
            .append(arg)
            .append(" .")
            .append(pagePathName)
            .append("\n");
}

There are other problems that buildIncludeDirective introduces in relation to clean code. It violates the "no side-effects" rule. The instance variable newPageContent is modified by the function and the only way to know that would be to look into the implementation details. In this case I would favour passing in the StringBuffer as an argument and let the function the modify it. This would make the intention of buildIncludeDirective clearer from the method signature, as well as making the function more portable if it were to be reused elsewhere.

private void buildIncludeDirective(StringBuffer content,
                                   String pagePathName,
                                   String arg) {
    content
            .append("\n!include ")
            .append(arg)
            .append(" .")
            .append(pagePathName)
            .append("\n");
}

A good rule-of-thumb for when it makes sense to break a piece of logic into it's own function is when it will be called in multiple places, or if the same logic is called with multiple variable arguments, like the include function for example. This, of course, would also be an example of the DRY (don't repeat yourself) rule.

Functions become redundant wrappers for other function calls #

One common symptom of the "smaller functions are better" mentality is functions which only call another function. They are, in essense, just a wrapper for another function, and are often redundent and simply clutter up your codebase and make it needlessly complicated. The findInheritedPage function from Listing 3-7 is an example of this problem as well as another function that is only called from one place.

private void include(String pageName, String arg) throws Exception {
    WikiPage inheritedPage = findInheritedPage(pageName);
    if (inheritedPage != null) {
        String pagePathName = getPathNameForPage(inheritedPage);
        buildIncludeDirective(pagePathName, arg);
    }
}
private WikiPage findInheritedPage(String pageName) throws Exception {
    return PageCrawlerImpl.getInheritedPage(pageName, testPage);
}

What you might say in defence of findInheritedPage is that it does abstract away the implemntation details of how the WikiPage object is found from the page name, but in this case since this function is only called from one place and is essentially just a wrapper for the PageCrawlerImpl.getInheritedPage function I would rather the implementation just be a part of the include function.

These problems may seem not so bad in this small example, but it is in larger, real world projects these issues become amplified and add a large amount of complexity to a codebase, despite the intention to follow the principles of clean code.

Comments are superior to many small functions #

The small functions in the above examples were introduced in order to make the code more readable and understandable. They have descriptive names and focused tasks which help to make it clear what the code does, but they introduce the problems I have already outlined. A simpler approach to this refactor would be to just introduce some comments.

Comments will explain the purpose and function of each part of the implementation, just like a descriptively named function would, but without nesting logic another layer deep in the call stack or adding redundant wrappers to other function calls. Additionally, when reading through the large function, you will be able to read each step in order and understand the implementation details, rather than having to seach down through the function calls to the operation actually being performed.

Let's make the code cleaner #

After understanding the problems introduced by developers religiously following the "small is better" rule, let's refactor the refactor from Clean Code and make it even cleaner.

package fitnesse.html;
import fitnesse.responders.run.SuiteResponder;
import fitnesse.wiki.*;

public class SetupTeardownIncluder {
    private PageData pageData;
    private WikiPage testPage;
    private PageCrawler pageCrawler;
    private StringBuffer newPageContent;
    public static String render(PageData pageData) throws Exception {
        return render(pageData, false);
    }
    public static String render(PageData pageData, boolean isSuite)
            throws Exception {
        return new SetupTeardownIncluder(pageData).render(isSuite);
    }
    private SetupTeardownIncluder(PageData pageData) {
        this.pageData = pageData;
        testPage = pageData.getWikiPage();
        pageCrawler = testPage.getPageCrawler();
        newPageContent = new StringBuffer();
    }
    private String render(boolean isSuite) throws Exception {
        // If this is a test page, include the setup and teardown pages
        if (pageData.hasAttribute("Test"))
            includeSetupAndTeardownPages(isSuite);
        return pageData.getHtml();
    }
    private void includeSetupAndTeardownPages(boolean isSuite)
            throws Exception {
        // Include setup pages
        if (isSuite)
            include(SuiteResponder.SUITE_SETUP_NAME, "-setup");
        include("SetUp", "-setup");

        // Include page content
        newPageContent.append(pageData.getContent());

        // Include teardown pages
        include("TearDown", "-teardown");
        if (isSuite)
            include(SuiteResponder.SUITE_TEARDOWN_NAME, "-teardown");

        // Update the page content
        pageData.setContent(newPageContent.toString());
    }
    private void include(String pageName, String arg) throws Exception {
        // Get The inherited page for the page name
        WikiPage inheritedPage = PageCrawlerImpl
            .getInheritedPage(pageName, testPage);
        // Avoid nesting ifs with early returns
        if (inheritedPage == null) return;

        // Get the path name for the inherited page
        WikiPagePath pagePath = pageCrawler.getFullPath(inheritedPage);
        String pagePathName = PathParser.render(pagePath);

        // Build the include directive
        newPageContent
                .append("\n!include ")
                .append(arg)
                .append(" .")
                .append(pagePathName)
                .append("\n");
    }
}

While I do think that this logic could just be a simple function as in it's original form (Listing 3-1), I don't hate the class-based approach Martin used for the refactor. In the spirit of doing only the work necessary to accomplish the task, I have only refactored Listing 3-7 enough to remove the problems I highlighted above. The call stack necessary to trace through in order to understand the code has been greatly reduced, the implementation details of each function are easy to see in one place and there are no redundent wrapper functions contributing to clutter and complexity. I also added comments to make up for the "self-documenting" nature of the "many small functions" approach.

We should work on the code cleaning which provides the most benefit first, and stop before we reach the point of dimishing returns. With heuristics, we must remember that they are useful only until they are not. You must understand why the rule is useful, so that you can know when it is not.

I have compromised on some of the principals discussed by Martin in chapter 3 of Clean Code, such as the rule of keeping different levels of abstraction in different functions (e.g. in the includeSetupAndTeardownPages), however clean code is all about trade-offs. Clean code is best when we trade a small bit of extra effort for cleanliness today in order to save much more effort in the future, but it is easy to reach a point of diminishing returns or worse still to make your code less clean by blindly applying heuristics.

Connect Nearby Devices Part 2: Local Networking Android

2020-01-11T00:00:00Z

This post will show you how to create an Android app that can run on multiple nearby devices and connect them via a local network. This is part 2 of a larger tutorial that will explain how you can connect an app to other instances of the same app running on multiple devices and platforms.

In part 1 of this tutorial we built an iOS app that can connect to other instances of the same app. In this part we will build an Android app that can connect and share data between other instances of the same Android app, and the iOS app from part 1.

Example Local Networking App #

I built and Android app that can join a realtime messaging chat with any other devices on the same local network. This is a port of the iOS app that was linked in part 1. These two apps can connect on the same network and join the same chat cross-platform on Android and iOS. The finished app is available here: Finished Example.

Connecting devices over a local network #

There are 2 parts to building this app, discovery and connection.

Discovery means we need devices running the same app to be able to see each other so that they can connect. For discovery we will use the native Android Network Service Discovery classes. This is equivalent and compatible with Bonjour on Apple devices and will allow us to publish and listen for services running on the same network. We can then get the ip address and port of the host device in order that we can connect.

For connection we will use TCP/IP sockets to connect our devices and pass messages back and forth. The classes from the native java.net package will provide the sockets that we need.

Hosting #

In order to maintain communication and a shared state between more than 2 devices, we will use a client-server model for this app. One device will act as a host, and every other device will act as a client of that host. Thus there will be a socket connection between each client and the host. The host must accept socket connections over the network.

First, we'll create a variable as a field of our Activity to hold our server socket.

var serverSocket: ServerSocket? = null

Then, when we want to start hosting, we'll initialize a server socket. Passing 0 as the port argument allows the system to provide us a port. We'll get and store this port number for use later.

// Create a listen socket
val port: Int
serverSocket = ServerSocket(0).also { socket ->
    // Store the chosen port.
    port = socket.localPort
}

The accept method of ServerSocket is a long running, blocking method that listens for a connection to be made. We will call the method in a while loop so that when a connection is made, we can hold on to the new client socket, and then the loop will call accept again and wait for the next client.

Since we are calling a blocking method in an indeterminate while loop, we will need to run this code in it's own thread so we do not block the execution of our app.

Thread(Runnable {
    while (serverSocket != null) {
        try {
            serverSocket?.accept()?.let {
                Log.d("ServerSocket", "accepted client")

                // Hold on to the client socket
                connectedClients.add(it)
            }
        } catch (e: SocketException) {
            break
        }
    }
}).start()

Now we have a thread that will execute our while loop until we decide to close our socket and set the value back to null. The server socket will wait to accept a connection from a client, and when it does, it will hold on to the client socket and the loop will run again and wait to accept the next client.

To get rid of the compiler error from the code above, we will add a variable as a field of our Activity that will hold onto the client sockets.

var connectedClients: MutableList<Socket> = CopyOnWriteArrayList<Socket>()

We are using CopyOnWriteArrayList to ensure the thread safety of mutations on our list of clients. This class is inefficient if we are planning to mutate it a lot and if the list size will be very large, but for our purposes it will work very well and ensure thread safety with very little work on our part.

Now we have a server socket that is accepting connections and keeping track of it's clients. In order for our clients to discover the server and connect, they need to know the ip address and port number of the host device. We can publish and discover our service over the network using NSD.

Using Android Network Service Discovery #

As the host device, we will be publishing a service over the network that client devices will be able to discover. First we need an instance of NsdManager which we will lazy load as a field on our activity.

val nsdManager: NsdManager by lazy {
    (getSystemService(Context.NSD_SERVICE) as NsdManager)
}

Next we will need an instance of NsdManager.RegistrationListener to listen for callbacks. You will want to add code to the functions you will override in order to respond to errors and other important events.

private val registrationListener = object : NsdManager.RegistrationListener {
    override fun onServiceRegistered(NsdServiceInfo: NsdServiceInfo) {
        // Save the service name. Android may have changed it in order to
        // resolve a conflict, so update the name you initially requested
        // with the name Android actually used.
        Log.d("NsdManager.Registration", "Service registered")
    }

    override fun onRegistrationFailed(serviceInfo: NsdServiceInfo, errorCode: Int) {
        // Registration failed! Put debugging code here to determine why.
        Log.d("NsdManager.Registration", "Registration failed")
    }

    override fun onServiceUnregistered(arg0: NsdServiceInfo) {
        // Service has been unregistered. This only happens when you call
        // NsdManager.unregisterService() and pass in this listener.
        Log.d("NsdManager.Registration", "Service unregistered")
    }

    override fun onUnregistrationFailed(serviceInfo: NsdServiceInfo, errorCode: Int) {
        // Unregistration failed. Put debugging code here to determine why.
        Log.d("NsdManager.Registration", "Unregistration failed")
    }
}

Once we have created a server socket and are accepting connections, we'll publish our service.

// Create the NsdServiceInfo object, and populate it.
val serviceInfo = NsdServiceInfo().apply {
    // The name is subject to change based on conflicts
    // with other services advertised on the same network.
    serviceName = "LocalNetworkingApp"
    serviceType = "_LocalNetworkingApp._tcp."
    setPort(port)
}

// Register the service for discovery
nsdManager.registerService(serviceInfo, NsdManager.PROTOCOL_DNS_SD, registrationListener)

The name and type of our service will be LocalNetworkingApp and we will specify TCP as the protocol (this could be a value such as "_http._tcp", for example, to specify an HTTP service). This will indicate that our service is for our local networking app and that the TCP protocol will be used.

Our service is now being broadcast over the local network so clients will be able to discover it and get the ip address and port number to connect to.

Clients #

Once one device running our app is acting as the host, the rest of the devices will act as clients. The first thing to do is to discover the service so we can connect to the address of the host. We will use an instance of NsdManager to discover our service.

nsdManager.discoverServices("_LocalNetworkingApp._tcp.", NsdManager.PROTOCOL_DNS_SD, discoveryListener)

We are looking for services of our type. The discoveryListener will be a field on our activity that is an instance of NsdManager.DiscoveryListener.

private val discoveryListener = object : NsdManager.DiscoveryListener {

    val TAG = "discoveryListener"

    // Called as soon as service discovery begins.
    override fun onDiscoveryStarted(regType: String) {
        Log.d(TAG, "Service discovery started")
    }

    override fun onServiceFound(service: NsdServiceInfo) {
        Log.d(TAG, "Service found ${service.serviceName}")

        nsdManager.resolveService(service, resolveListener)
    }

    override fun onServiceLost(service: NsdServiceInfo) {
        // When the network service is no longer available.
        // Internal bookkeeping code goes here.
        Log.e(TAG, "service lost: $service")
    }

    override fun onDiscoveryStopped(serviceType: String) {
        Log.i(TAG, "Discovery stopped: $serviceType")
    }

    override fun onStartDiscoveryFailed(serviceType: String, errorCode: Int) {
        Log.e(TAG, "Discovery failed: Error code:$errorCode")
        nsdManager.stopServiceDiscovery(this)
    }

    override fun onStopDiscoveryFailed(serviceType: String, errorCode: Int) {
        Log.e(TAG, "Discovery failed: Error code:$errorCode")
        nsdManager.stopServiceDiscovery(this)
    }
}

The important method above is onServiceFound. Once we have discovered our service, we need to resolve it using an instance of NsdManager.ResolveListener. Create another field on your activity called resolveListener and one called socket to hold the socket that will connect to the host.

var socket: Socket? = null

private val resolveListener = object : NsdManager.ResolveListener {

    val TAG = "resolveListener"

    override fun onResolveFailed(serviceInfo: NsdServiceInfo, errorCode: Int) {
        // Called when the resolve fails. Use the error code to debug.
        Log.e(TAG, "Resolve failed: $errorCode")
    }

    override fun onServiceResolved(serviceInfo: NsdServiceInfo) {
        Log.e(TAG, "Resolve Succeeded. $serviceInfo")

        socket?.let {
            Log.i(TAG, "Socket already connected $it")
            return
        }

        try {
            // Connect to the host
            socket = Socket(serviceInfo.host, serviceInfo.port)
        } catch (e: UnknownHostException) {
            Log.e(TAG, "Unknown host. ${e.localizedMessage}")
        }
    }
}

Assuming no exception was thrown we now have a socket connected to a host device.

That's it! Now our app has the ability to connect with other instances of itself running on the same network.

Of course the whole point on this is so that we can pass messages between them, so let's go over reading and writing to sockets.

Sending Messages #

As long as our devices are connected, we will be constantly reading a stream of data coming over the network. In order to know when a message begins and ends we will use a terminator. To comply with our iOS app from the previous part of this tutorial, we will use "\r\n". Add this to the top of your Kotlin Activity file, below the imports:

const val MESSAGE_TERMINATOR = "\r\n"

First, let's create a class in our activity for the host device that will read messages from connected clients. Since we will be creating an indeterminate while loop, this class will be a subclass of Runnable so we can pass it as an argument to a new thread.

inner class ClientReader(private val client: Socket): Runnable {
    val TAG = "ClientReader"

    override fun run() {
        var line: String?
        val reader: BufferedReader

        try {
            reader = BufferedReader(InputStreamReader(client.getInputStream()))
        } catch (e: IOException) {
            Log.w(TAG, "BufferedReader failed to initialize")

            connectedClients.remove(client)
            return
        }

        while (true) {
            try {
                line = reader.readLine()

                if (line == null) {
                    connectedClients.remove(client)
                    break
                }

                Log.d(TAG, "Read line $line")

            } catch (e: IOException) {
                connectedClients.remove(client)
                break
            }
        }
    }
}

Each iteration of the while loop will call the readLine method of BufferedReader, which will read until our terminator. If the connection is terminated we will remove the client and break the while loop in order to end the execution of our Runnable.

When a host accepts a new client, we will start reading from the socket immediately. Modify your code where you are accepting clients on the ServerSocket so it looks like this:

Thread(Runnable {
    while (serverSocket != null) {
        try {
            serverSocket?.accept()?.let {
                Log.d("ServerSocket", "accepted client")

                // Hold on to the client socket
                connectedClients.add(it)

                // Start reading messages
                Thread(ClientReader(it)).start()
            }
        } catch (e: SocketException) {
            break
        }
    }
}).start()

Now when our host accepts a new connection, we will start reading reading from the client socket on a new thread, which will continue until the client disconnects.

We'll create a similar reader class for our clients to use.

inner class ServerReader(private val socket: Socket): Runnable {
    val TAG = "ServerReader"

    override fun run() {
        var line: String?
        val reader: BufferedReader

        try {
            reader = BufferedReader(InputStreamReader(socket.getInputStream()))
        } catch (e: IOException) {
            Log.w(TAG, "BufferedReader failed to initialize")

            socket = null
            return
        }

        while (true) {
            try {
                line = reader.readLine()

                if (line == null) {
                    socket = null
                    break
                }

                Log.d(TAG, "Read line $line")

            } catch (e: IOException) {
                socket = null
                break
            }
        }
    }
}

The difference here is that when the server disconnects we will set our socket to null rather than removing a client like we did for the server.

When we want to send a message through the socket, wether it is from the client to the server or from the server to the client, we will use a subclass of Writer initialized with the output stream of the socket.

val writer: PrintWriter

try {
    writer = PrintWriter(socket.getOutputStream())
} catch (e: IOException) {
    // If the writer fails to initialize there was an io problem, close your connection
}

Then when you are ready to write a message call print and flush.

writer.print("Hello from the network!" + MESSAGE_TERMINATOR)
writer.flush()

Make sure to append the terminator to your message, so you know when to stop reading.

When you are done sending messages and ready to disconnect and close the socket, make sure you close your writer.

writer.close()

When we want to end the connection from the host or stop hosting we should do some cleanup.

if (host) {
    // Stop listening
    serverSocket?.close()
    serverSocket = null

    // Stop broadcasting service
    nsdManager.unregisterService(registrationListener)

    // Remove the clients
    connectedClients.forEach {
        it.close()
    }
} else {
    try {
        nsdManager.stopServiceDiscovery(discoveryListener)
    } catch (e: IllegalArgumentException) {
        Log.i("nsdManager", "discoveryListener not registered")
    }

    socket?.close()
    socket = null
}

Done #

This should be all you need to get started connecting multiple devices running the same app over the local network and sending messages back and forth. For a complete example of an app doing this, you can see my example messaging app.

You can see part 1 of this tutorial series to build an iOS app that can connect to this one here.

In future parts of this series I will explain how to accomplish the same thing using Bluetooth communication. If there's anything I didn't explain or anything else you want to know, I'd love it if you left a comment.

Connect Nearby Devices Part 1: Local Networking iOS

2019-11-09T00:00:00Z

Want to create an app that connects to nearby devices running the same app and is able to share data without going over the internet? So did I, but I had a hard time finding a good source of information online to teach me how to do that. In this series I'm going to explain how to create an app that can connect many devices running iOS or Android and share data between them.

The first part of this seriers will teach you to build an iOS app that can connect to other devices over a Local Area Network. Further parts of this series will cover Android as well as using Bluetooth as an alternative strategy to connect nearby devices.

Example Local Networking App #

I built an iOS app that can join a realtime messaging chat with any other devices on the same local network. The first person who joins the chat will become the host and other people running the app that join the chat will be connected to the host. Everyone will be assinged a random name after a character from the Belgariad. You can follow along with this tutorial and build you own app, or you can also download the repository of the finished app here: Finished Example.

Connecting devices over a local network #

There are 2 parts to building this app, discovery and connection.

Discovery means we need devices running the same app to be able to see each other so that they can connect. For discovery we can use Bonjour, an open source technology which allows a device to publish and listen for services running on the same network. We can then get the ip address and port of the host device in order that we can connect.

For connection we can use TCP/IP sockets to connect our devices and pass messages back and forth. The library I chose to use for this is called CocoaAsyncSocket.

CocoaAsyncSocket #

The first thing to do, following the intructions in the Readme, is to install CocoaAsyncSocket in your project. Use CocoaPods and add this line to your Podfile:

use_frameworks! # Add this if you are targeting iOS 8+ or using Swift
pod 'CocoaAsyncSocket'

The class we are going to be using from CocoaAsyncSocket is called GCDAsyncSocket. It is a thread-safe TCP/IP socket that runs entirely within it's own GCD queue and uses a delegate pattern to execute callbacks on the queue you supplied. Sockets are used to connect two devices over a network so that they can exchange messages. If any of this is sounding new or unfamiliar to you I highly recommend reading the CoacoaAsyncPods wiki. The wiki does an excellent job introducing networking concepts and reading and writing using the GCDAsyncSocket library.

Hosting #

We'll create a variable as a property of our view controller to hold our socket as well as a dispatch queue for the socket to do work in.

var socket: GCDAsyncSocket?
let socketQueue = DispatchQueue.init(label: "HostSocketQueue")

Then, when we want to start hosting, we'll initialize a socket and start accepting connections.

// Create the listen socket
socket = GCDAsyncSocket(delegate: self, delegateQueue: socketQueue)
do {
    try socket?.accept(onPort: 0)
} catch let error {
    print("ERROR: \(error)")
    return
}

Passing 0 as the port argument allows the system to provide us a port. You can get the port number after the accept invocation.

let port = socket!.localPort

Now our host device has a socket that is accepting connections. We need our view controller to adopt the GCDAsyncSocketDelegate protocol to get a callback when new sockets are accepted. When a client device connects, we will get a reference to the client's socket. We'll create another property on our view controller to hold the connected client sockets.

var connectedSockets: [GCDAsyncSocket] = []

Then we will implement a method of the GCDAsyncSocketDelegate protocol.

func socket(_ sock: GCDAsyncSocket, didAcceptNewSocket newSocket: GCDAsyncSocket) {
    connectedSockets.append(newSocket)
}

Now we have a reference to the socket on the connected client device. This is what we, the host device, will use to read data from and write to. When the client disconnects, we will want to remove the socket from our connectedSockets array, so we'll implement another delegate method.

func socketDidDisconnect(_ sock: GCDAsyncSocket, withError err: Error?) {
    print("Socket did disconnect \(err?.localizedDescription ?? "")")
    if let index = connectedSockets.firstIndex(of: sock) {
        connectedSockets.remove(at: index)
    }
}

That covers the basic lifecycle of creating a socket to accept connections, and getting connected client sockets to read and write messages, but there is one more thing the host needs to do.

In order for clients to connect, they need to know the ip address and port number of the host device. We can publish and discover our service over the network using Bonjour, also known as zero-configuration networking.

NetService #

As the host device, we will be publishing a service over the network that client devices will be able to discover. We need to use the NetService class to accomplish this. First, create a new view controller property to reference an instance of NetService.

var netService: NetService?

Once we have created a socket and are accepting connections, we'll publish our service.

// Publish a NetService
netService = NetService(domain: "local.", type: "_LocalNetworkingApp._tcp.", name: "LocalNetworkingApp", port: Int32(port))
netService?.delegate = self
netService?.publish()

When initializing our NetService, we use "local". to limit registration to the local domain. The type of our service we will call LocalNetworkingApp and we will specify TCP as the protocol (this could be a value such as "_http._tcp", for example, to specify an HTTP service). We also give it a name and provide the port that our socket is accepting connections on.

Our view controller will need to adopt the NetServiceDelegate protocol. As a host you will be interested in the following delegate methods:

func netServiceDidPublish(_ sender: NetService) {
    print("Bonjour Service Published: domain(\(sender.domain)) type(\(sender.type)) name(\(sender.name)) port(\(sender.port))")
}

func netService(_ sender: NetService, didNotPublish errorDict: [String : NSNumber]) {
    print("Failed to publish Bonjour Service domain(\(sender.domain)) type(\(sender.type)) name(\(sender.name))\n\(errorDict)")
}

The call to netService?.publish() finally makes our service discoverable by the client devices.

Clients #

Once one device running our app is acting as the host, the rest of the devices will act as clients. The first thing to do is to discover the service so we can connect to the address of the host. For this we can use the NetServiceBrowser class. As always, use a property on your view controller to hold your instance of NetServiceBrowser.

var netServiceBrowser: NetServiceBrowser?

Then when we are ready to discover a service we will initialize the browser and search for our service.

netServiceBrowser = NetServiceBrowser()
netServiceBrowser?.delegate = self
netServiceBrowser?.searchForServices(ofType: "_LocalNetworkingApp._tcp.", inDomain: "local.")

Of course, we'll need our view controller to adopt the NetServiceBrowserDelegate protocol. When we find the service published by the host, we'll grab an instance of the host NetService and attempt to resolve it.

extension ViewController: NetServiceBrowserDelegate {
    func netServiceBrowser(_ browser: NetServiceBrowser, didNotSearch errorDict: [String : NSNumber]) {
        print("ERROR: \(errorDict)")
    }

    func netServiceBrowser(_ browser: NetServiceBrowser, didFind service: NetService, moreComing: Bool) {
        if netService == nil {
            netService = service
            netService?.delegate = self
            netService?.resolve(withTimeout: 5)
        }
    }

    func netServiceBrowserDidStopSearch(_ browser: NetServiceBrowser) {
        print("NetServiceBrowser did stop search")
    }
}

When the NetService resolves, we will get a callback through the methods of the NetServiceDelegate protocol. First let's create a variable to hold the server addresses that will be returned by the service.

var serverAddresses: [Data]?

Then implement the NetServiceDelegate methods.

func netService(_ sender: NetService, didNotResolve errorDict: [String : NSNumber]) {
    print("NetService did not resolve: \(errorDict)")
}

func netServiceDidResolveAddress(_ sender: NetService) {
    if serverAddresses == nil {
        serverAddresses = sender.addresses
    }
    if socket == nil {
        socket = GCDAsyncSocket(delegate: self, delegateQueue: socketQueue)
        connectToNextAddress()
    }
}

We hold on to the addresses of the host we will connect to. We also created a socket which will connect to the host address. Let's look at the connectToNextAddress() method.

func connectToNextAddress() {
    var done = false
    while (!done && serverAddresses?.count ?? 0 > 0) {
        if let addr = serverAddresses?.remove(at: 0) {
            do {
                try socket?.connect(toAddress: addr)
                done = true
            } catch let error {
                print("ERROR: \(error)")
            }
        }
    }

    if !done {
        print("Unable to connect to any resolved address")
    }
}

Here we try to connect to the addresses resovled by the host service that we discovered. When the socket connects to the host, we will be notified via a delegate method of GCDAsyncSocketDelegate. We'll create a boolean view controller property to track wether we as the client are connected.

var connected = false

Then we'll update the value in our GCDAsyncSocketDelegate methods.

func socket(_ sock: GCDAsyncSocket, didConnectToHost host: String, port: UInt16) {
    print("Socket did connect to host \(host) on port \(port)")
    connected = true
}


func socketDidDisconnect(_ sock: GCDAsyncSocket, withError err: Error?) {

    // ...

    connected = false
}

That's it! Now our client devices can discover and connect to the host device. Our app has the ability to connect with other instances of itself running on the same network.

Of course the whole point of this is so that we can pass messages between them, so let's talk about reading and writing a bit.

Sending Messages #

As long as our devices are connected, we want to be constantly reading a stream of data coming over the network. In order to know when a message begins and ends we will use a terminator. There are other ways to do this, such as reading certain lenghts of data at a time, but for simplicity's sake, we'll say that a message ends with the string '\r\n'. Fortunately, GCDAsyncSocket provides this as Data for us using the GCDAsyncSocket.crlfData() static method.

When a host accepts a new client, we want to start reading from the socket immediately, until we reach our terminator.

func socket(_ sock: GCDAsyncSocket, didAcceptNewSocket newSocket: GCDAsyncSocket) {

    // ...

    // Wait for a message
    newSocket.readData(to: GCDAsyncSocket.crlfData(), withTimeout: -1, tag: ViewController.MESSAGE_TAG)
}

When a client connects to the host, we also want to start reading immediately from the socket.

func socket(_ sock: GCDAsyncSocket, didConnectToHost host: String, port: UInt16) {

    // ...

    // Connected to host, wait for a name
    socket?.readData(to: GCDAsyncSocket.crlfData(), withTimeout: -1, tag: ViewController.NAME_TAG)
}

The tag argument is an integer that is used to distinguish types of messages. That means the only data that will be read by this invocation is data sent using the same tag. In my case, the messaging app will assign a name to the client when they connect, so as the client the first message we want to read is a name.

We can send any Data over the network, but if we want to send a string, it's as simple as encoding the string and sending it over the socket. Of course we must end our message with the terminator so we know when to stop reading, so we'll append the terminator data to our message. In the client's case that will look like this:

guard var data = "Hello, world!".data(using: .utf8) else {
    print("ERROR: Couldn't encode string")
    return
}
data.append(GCDAsyncSocket.crlfData())
socket?.write(data, withTimeout: -1, tag: ViewController.MESSAGE_TAG)

For the host we may want to send a message to an individual client by writing to just their socket, or we may want to send a message to all the connected clients.

for client in connectedSockets {
    client.write(data, withTimeout: -1, tag: ViewController.MESSAGE_TAG)
}

Wether we are the host or a client, we will read data using the GCDAsyncSocketDelegate method.

func socket(_ sock: GCDAsyncSocket, didRead data: Data, withTag tag: Int) {
    // We may want to read messages differently depending on the tag
    print("Socket did read data with tag \(tag)")

    // If our data is a string we can decode it
    if let string = String(data: data, encoding: .utf8) {
        print(string)
    }

    // Finally we should continue to read data from the socket
    sock.readData(to: GCDAsyncSocket.crlfData(), withTimeout: -1, tag: ViewController.MESSAGE_TAG)
}

Of course this Data could contain JSON strings, images or anything else you want to send.

Finishing Up #

When we want to end the connection from the host or stop hosting we should do some cleanup.

if host {
    // Stop listening
    socket?.disconnect()

    netService?.stop()
    netService = nil

    // Remove the clients
    for socket in connectedSockets {
        socket.disconnect()
    }

    socket = nil

} else {
    netServiceBrowser?.stop()
    socket?.disconnect()
    socket = nil
    netService = nil
    serverAddresses = nil
}

Done #

There are a few more details to pay attention to, but the above should cover the essentials of how to connect multiple devices running the same app over the local network and send messages back and forth. For a complete example of an app doing this, you can see my example messaging app.

Part 2 of this tutorial series shows how to build an Android app that can connect to this one, which can be found here

Build a static site with Jekyll

2018-05-12T00:00:00Z

Want to build an awesome static site like the one you are visiting right now? This post will explain step by step how I built this blog with Jekyll, installed a custom theme and hosted it on the web with GitHub pages.

Why Jekyll? #

I've been wanting to put more work into building an online presence lately, so I decided I should start blogging. I have used WordPress in the past, and had a great experience with it. I built my own custom template for fun and something to write about, and I even hosted it from my house on an old Ubuntu box I had around. It was fun and a great learning experience, but this time around I was looking for something a little lighter -- something easier. I found Jekyll.

Jekyll is a static site generator written in Ruby and available as a gem. It allows you to write posts in markup and uses layouts to generate your static site. The end result is a databaseless, well formatted and indexable site with little or no Javascript that is up and running in no time. The cherry on top is that you can deploy your site to GitHub pages for free hosting and even use a custom domain.

Getting started #

There are excellent docs available at the Jekyll site (I recommend doing at least some reading), but if you want a guide that covers every step from installation to deployment, this is it.

First install the bundler and start a new site:

~ $ gem install bundler jekyll
~ $ jekyll new my-blog
~ $ cd my-blog

Once you are in your site directory you can start a development server:

~/my-blog $ bundle exec jekyll serve

Now you can browse to http://localhost:4000 and see your site. A new Jekyll site contains example content that will teach you how to write posts and configure basic settings. This is very useful to read through.

Install a theme #

The default theme included with Jekyll is Minima, which is simple and effective, but if you're like me you'll want something a bit more exciting and a bit more personal. GitHub Pages has a list of supported themes, but there are many open-source themes available. Jekyll Themes is a wonderful resource for beautiful pre-built themes. For this site, I used Hydeout.

There are two ways to install and use a theme. I will explain both here and leave the decision about what's best up to you.

Install a theme using a gem #

When you install a theme with a gem, the guts of the theme are hidden outside of your project, and your theme can be updated by simply changing your Gemfile.

To install a theme, replace the Minima gem in your Gemfile (my-blog/Gemfile) with the appropriate gem for your theme.

gem "jekyll-theme-hydeout", "~> 3.4"

Run bundle install to install the gem. You will also need to replace the theme in your _config.yml file.

theme: jekyll-theme-hydeout

While we are in _config.yml, there are some important settings to add for the Hydeout theme.

markdown: kramdown
highlighter: rouge

plugins:
  - jekyll-feed
  - jekyll-gist
  - jekyll-paginate

paginate: 5 # This will show posts on your home page

Hydeout also requires that you move your index.md file to index.html and replace the contents with the following:

---
layout: index
title: My Title
---

Now run your site with bundle exec jekyll serve and you can see your new theme.

Install a theme manually #

If you would like to be able to edit the layout files of a theme, and have complete control over the result of your generated site, you can download a theme and install it manually. In the case of Hydeout this also provided me with much more sample content to work with and modify for my own use such as pages, sidebar links and posts.

Download the Hydeout, or any other theme you like. Then simply copy contents of the theme into your project.

~/my-blog $ cp -r ~/hydeout-master/* .

Run your site with bundle exec jekyll serve.

Deploy your site to GitHub Pages #

Jekyll makes it easy to deploy your website to GitHub pages. You will be able to host your site at https://yourgithubname.github.io or use any custom domain you own. Make sure you have git installed and you have a GitHub account.

Create a repository for your site. The project name must be username.github.io where username is your GitHub username.

Initialize a repository in your project.

~/my-blog $ git init

Before you add or commit any files, make sure to setup an appropriate .gitignore file. I used the .gitignore that was contained the Hydeout repository. Now you can add and commit your files, then push to your site to GitHub.

~/my-blog $ git add .
~/my-blog $ git commit -m 'initial commit'
~/my-blog $ git remote add origin https://github.com/username/username.github.io
~/my-blog $ git push -u origin master

GitHub will build your site and publish it to https://username.github.io.

Configure a custom domain #

I registered a domain through GoDaddy. I was able to use a custom domain for my GitHub Pages site by configuring some DNS settings.

First, in the settings for your project on GitHub, scroll down to the GitHub Pages options and add your domain name in the text box then save.

In the DNS settings for my domain I added A records with the following ip addresses:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Done #

Actually you are far from done. You will want to give your site a great title and description, edit or add some pages and maybe write a post or two. I also added Disqus and Google Analytics to my site right away by adding a few lines to _config.yml. The source for this site is available on my GitHub profile.

I'm also happy to answer any questions about how I built this website in the comments below or on my Twitter.

Hello World

2018-05-08T00:00:00Z

Tonight I am deploying this Jekyll powered blog to GitHub pages and setting up my domain.

This blog is a place for me to share things I have learned with the world, to document my coding experiments and side project and to serve as my about page on the web.

I remember fondly internet 1.0 when personal webpages were in vogue. At that time I was learning about HTML and was facinated with the technology. As a kid I never really knew where to go from there. Now that blogs are a "must have" for anyone wanting to be present on the web, I realize that I should have valued my little personal web page just as much as any other website I visited.

This is going to be the page I always wanted to build.

Brendan Innis

Building Your First App for visionOS: Part 2

Adding a 3D bar chart #

Drawing the chart #

Drawing a base plate #

Labelling the rows #

Labelling the columns #

Testing the 3D chart #

Next Steps #

Building Your First App for visionOS: Part 1

New visionOS project #

Exploring the new visionOS project #

Starting from scratch #

Building the spreadsheet UI #

Showing 3D content in a volumetric window #

Next steps #

So I rebuilt my blog using Eleventy

Why Eleventy? #

The Good #

The Bad #

Images #

Syntax Highlighting #

Summing It Up #

Coding Makes You Less Creative

Naming things and predictability #

Concise is clean and boring is better #

It's not all bad #

Getting started with RealityKit 1: Programmatically placing content in RealityKit

Create an augmented reality app #

Load 3D assets programmatically from USDZ files #

Pre-load 3D resources #

Programmatically place content in the real world #

Configure ARSession #

Translate tap locations into real world positions #

Complete project #

How to choose an anchor for your RealityKit iOS AR app

ARAnchors and AnchorEntities #

ARSessionDelegate #

Anchoring your scene #

Tap to place your scene #

Putting it all together #

You Should Be Using Cloudflare For Your Website

Cloudflare Provides An SSL Certificate #

Cloudflare Provides DNS Management, a CDN and Caches Your Website #

Cloudflare Provides Detailed Analytics For Free Without Any Setup #

Cloudflare Automatically Protects Your Website From Most Attacks #

Cloudflare Optimizes Your Code For You #

Cloudflare is Free, Easy and Just Awesome #

What I Learned Publishing My First App

Consider creating accounts for your developer self. #

You need a developer account. #

What OS Versions Should I Support? #

You need an app icon. #

You need screenshots. #

You need a website. #

You need a privacy policy. #

Plan to spend a good amount of time on your app listing. #

Organic growth is not dead. #

Don't hoard your effort and talent to yourself, share it with the world. #

Make an App Icon With Swift UI

Why use Swift UI to create your app icon #

Create a Swift UI view for an app icon #

Draw the icon #

Create the reference icon image #

Resize the reference image to required icon sizes #

Add your new app icon to your Xcode project #

Functions: Why Smaller is Not Always Better

The function to be refactored (Listing 3-1) #

Matin's refactor according to the principals of clean code (Listing 3-7) #

Lots of small functions lead to deep call stacks #

Implementation details get hidden in functions which are only called from one place #

Functions become redundant wrappers for other function calls #

Comments are superior to many small functions #

Let's make the code cleaner #

Connect Nearby Devices Part 2: Local Networking Android

Example Local Networking App #

Connecting devices over a local network #

Hosting #

Using Android Network Service Discovery #

Clients #