KAKELOG

Getting Started p5.js in TypeScript

Sun, 20 Feb 2022 00:00:00 +0900

Introduction

p5.js is a JavaScript port of Processing which is one of the most famous and easy to write frameworks for creative coding. Though it is so powerful as-is, we can unleash developer experience such as code completion by using p5.js in TypeScript.

In this post, we will explore a minimum configuration to get started developing a p5 sketch in TypeScript.

Summary

Install p5 and types by npm
Use Parcel to compile TS and run a dev web server

Installing packages

First of all, create a default package.json file and add the following Node packages.

$ npm init -y
$ npm i --save p5
$ npm i --save-dev @types/p5
$ npm i --save-dev parcel

In this post, we use Parcel to get the following benefits without writing much configurations.

Compiling TypeScript codes
Building HTML that references the compiled codes
Hosting a dev web server
Watching changes in the source codes to trigger re-compile & re-build

Creating the first sketch

Create src/index.html and src/sketch.ts files. Examples are as follows.

src/sketch.ts

import p5 from 'p5';

const sketch = (p: p5) => {
  p.setup = () => {
    p.createCanvas(400, 400);
  };

  p.draw = () => {
    p.background('#3178c6');
  };
};

new p5(sketch);

p5.js has “instance mode” which is explained in the reference to avoid adding p5 functions to global scope. Instead of declaring setup() or draw() functions globaly, we can instantiate a new insatance of p5 with a runnable function.

src/index.html

<!DOCTYPE html>
<html>
<head>
  <title>Sketch</title>
  <meta charset="utf-8">
  <script type="module" src="sketch.ts"></script>
</head>
<body>
  <main></main>
</body>
</html>

Note that src/index.html references the .ts version of the code. Parcel will compile the TypeScript code and output a HTML that references the compiled JavaScript code.

Also, the script tag has an attribute type="module" that is required to use ES modules and CommonJS syntax for exports and imports in the referenced script. This behavior is described in the official doc for migration from V1 to V2.

Running dev server

Add a new property soruce in the package.json file. This indicates the entry point of the page, and Parcel uses this for the target of the commands.

And add a new script in scripts for short hand to run parcel command.

{
  "source": "src/index.html",
  "scripts": {
    "dev": "parcel --port 8080"
  }
}

With this script, a dev server can be launched by $ npm run dev on port 8080.

The sketch will be running on localhost:8080 on a web browser. And also, any changes in the source files will trigger auto re-build and reload of the page.

Conclusion

p5.js and the definition of its types could be installed by npm. And by using Parcel, we could set up TS dev environment with a little configuration.

The code completion with TypeScript is so powerful, and I can not back to pure JS ever.

:see_no_evil:

References

p5.js
- home | p5.js
- reference | p5()
Parcel
- Parcel
- Migration

Unity AR - 平面の上でキャラクターを歩かせる

Wed, 20 Jan 2021 00:00:00 +0900

前回までで AR シーンの中で平面検出ができるようになったので，今回はその平面の上でキャラクターを歩かせてみる．歩くロジックはとても単純かつ雑なので，そんなに参考にはならないかもしれない．

概要

人型のモデルに Animator を設定して歩くアニメーションを再生する
ARPlane の FilterMesh から頂点を取得して，そこに向かって並行移動させる

環境

Unity 2020.1.17f1
AR Foundation 4.1.1
ARKit XR Plugin 4.1.1
iOS 14.3

アニメーションを再生する

まずは通常のシーンのなかでキャラクターにアニメーションを設定して再生する．モデルは出来合いのものを使っていく．今回は Unity 公式の Space Robot Kyle を使う．

シーンに配置してスケールを調整しておく．机の上を動き回る小さなロボにしたいので，XYZ それぞれ調整して Transform でネストしておく．ルートとなる Transform が (x,y,z) = (0,0,0) のときにモデルが接地しているように気を付ける．

Kyle に含まれるのは 3D モデルとテクスチャのみで，アニメーションは設定されていないので，自前で設定していく．といっても Animation Clip から作っていると終わらないので，Asset Store から良さそうなものを探して使っていく．今回は Basic Motions FREE Pack を使わせてもらう．

Kyle のモデルはデフォルトでは Rig が Legacy になっているので，これを Humanoid に変更する． Apply を実行すればモデルを元に自動で rigging され，Animator に対応した Avatar が作られる．

Animation Type	Rigging Result

Fig. Rigging の結果

あとは Kyle の Animator コンポーネントに Basic Motions Pack に含まれる適当な Animator Controller を設定すれば Kyle をアニメーションさせることができる．

Fig. 歩くアニメーション

アニメーションの状態を遷移させる

せっかくなので Animator Controller を作って状態遷移を定義し，Basic Motions Pack に含まれるいくつかのアニメーションを使えるようにしてみる（追記：でも歩くアニメーション以外は結局使わなかったという）．

ここでは，Idle，Walking，Running，Running Backward の4つの状態を定義する．

Fig. Animator (ステートマシン)

Parameters には velocity を追加して，状態遷移の条件（Conditions）に使用する．適当にスクリプトを書いて Inspector から velocity を手動で変更できるようにしてシーンを実行してみる．

using UnityEngine;

[RequireComponent(typeof(Animator))]
public class Walker : MonoBehaviour
{
    private static readonly int AnimatorVelocity = Animator.StringToHash("velocity");

    [SerializeField] private Animator animator;

    [SerializeField] private int velocity;

    private void Update()
    {
        animator.SetInteger(AnimatorVelocity, velocity);
    }
}

Fig. アニメーションの切り替え

キャラクターの位置を動かす

歩くというアニメーションは Animator で再生できるようになったので，そのアニメーションに合わせてそれらしい速度で平行移動させる．平面（Plane）のメッシュを与えて，その中の頂点（Vertex）をひとつランダムで選び，そこに向かって移動させる．

Mesh の各頂点は vertices で取得できる．頂点の座標は Mesh に対するローカル座標なので， TransformPoint() でワールド座標に変換する．目的地の座標が取得できたら，あとは Kyle が目的地を向くように回転させて並行移動させる．同時にアニメーションを再生して，歩いて移動しているっぽく見せる．

using UnityEngine;

[RequireComponent(typeof(Animator))]
public class Walker : MonoBehaviour
{
    private static readonly int AnimatorVelocity = Animator.StringToHash("velocity");

    [SerializeField] private Animator animator;

    [SerializeField] private int velocity;

    [SerializeField] private float walkingSpeed = 0.18f;
    [SerializeField] private float runningSpeed = 0.54f;

    [SerializeField] private MeshFilter ground;

    private Vector3 _destination = Vector3.zero;

    private void Update()
    {
        animator.SetInteger(AnimatorVelocity, velocity);

        var distance = Vector3.Distance(transform.position, _destination);
        if (distance <= 0.001f)
        {
            if (ground == null) return;
            var vertices = ground.sharedMesh.vertices;
            if (vertices.Length == 0) return;

            var destination = vertices[Random.Range(0, vertices.Length)];
            _destination = ground.transform.TransformPoint(destination);

            return;
        }

        var transformVelocity = 0.0f;
        if (velocity > 1) transformVelocity = runningSpeed;
        else if (velocity > 0) transformVelocity = walkingSpeed;

        var transformLerp = (Time.deltaTime * transformVelocity) / distance;

        transform.position = Vector3.Lerp(transform.position, _destination, transformLerp);
        transform.LookAt(_destination, ground.transform.up);
    }
}

適当なスクリプトなので，変数 ground として MeshFilter 型を取るものの，平面じゃない MeshFilter を与えられたら Kyle が地面にめりこんでしまうはずだが，今回は平面しか対象にしないので気にしないこととする．

Fig. Plane の上を歩くテスト

AR シーンの中で動かす

前回は検出した平面の上に樹木のモデルを置いていたが，同様に Kyle を置いてみる．

if (raycastManager.Raycast(touch.position, _raycastHits, TrackableType.PlaneWithinPolygon))
{
    var hit = _raycastHits.First();
    if (hit.trackable is ARPlane)
    {
        var instance = Instantiate<GameObject>(arObjectPrefab, hit.pose.position, hit.pose.rotation);

        var walker = instance.GetComponent<Walker>();
        var ground = hit.trackable.GetComponent<MeshFilter>();
        if (walker != null && ground != null)
        {
            walker.SetGround(ground);
            walker.SetWalking(true);
        }
    }
}

置くものは結局のところ GameObject なので Spawn() する arObjectPrefab を Kyle に差し替えるだけ． ARPlane には MeshFilter が付いているはずなので，GetComponent() して地面として設定する．

ついでに prefab を切り替えられるボタンを適当に作って，色々と置いてみる．

Fig. ARPlane の上を歩く

という感じで ARPlane の上を歩けるようになった．

まとめ

AR シーンの中で検出した平面の上でキャラクターを歩かせてみた．

キャラクターは人型のアセット（具体的には Space Robot Kyle）を使用した
人型のアセットに歩くアニメーションを設定した（具体的には Basic Motions FREE Pack）
Animator を組んで，状態遷移できるようにした
ARPlane から取得した MeshFilter の上を歩くようにした
MeshFilter からランダムに頂点（vertices）を取得して，それを目的地として歩くようにした

Unity というゲームエンジンや Asset Store というエコシステムを使っているだけなので，技術的にどうこうということはなかった．

というか，いまさらだが Terrain の上を歩かせる方法とか普通にある気がする（が気にしないこととする）．

:dancer:

References

Unity iOS の AR アプリ開発をはじめる

Wed, 13 Jan 2021 00:00:00 +0900

Unity iOS で AR アプリの開発をはじめるためのセットアップ方法のメモ． AR Foundation の提供する仕組みの範囲で，簡単な平面検出と 3D モデルの配置をやってみる．

概要

Unity iOS で AR アプリ開発ことはじめとして，次のことをやってみる．

AR Foundation & ARKit をセットアップする
AR Plane Manager で平面検出し，デフォルトのビジュアライザで平面を表示する
AR Raycast Manager で AR Plane のどこをタッチしたのか判定する
タッチした場所に適当な 3D オブジェクトを表示する

環境

Unity 2020.1.17f1
AR Foundation 4.1.1
ARKit XR Plugin 4.1.1
iOS 14.3

Unity で ARKit を使う準備をする

パッケージのインポート

まずは Unity で AR を使うための準備をする． Package Manager を開いて，次のパッケージをインポートする．

AR Foundation (Version 4.1.1)
ARKit XR Plugin (Version 4.1.1)

Unity はマルチプラットフォームの AR アプリ開発をサポートしている． AR Foundation は各プラットフォームをまとめて抽象化するラッパーで，各プラットフォームごとの実装は plugin として分離されている．

ARKit の有効化

インポートが完了したら Project Settings を開いて ARKit を有効化する．

XR Plug-in Management
- iOS > Plug-in Providers > ARKit にチェックを入れる
XR Plug-in Management > ARKit
- Requirement を Required にする
Player > iOS > Other Settings
- Target minimum iOS Version を適当なものにする
- Requires ARKit support にチェックを入れる
- Camera Usage Description に適当な文言を入れる

AR Session の配置

Scene に AR Session と AR Session Origin を配置する．ただそれだけ．

AR Session State の表示

Session が動いているのか分かるように，状態を画面に表示しておく．

using System.Collections;
using UnityEngine;
using UnityEngine.XR.ARFoundation;

public class AppController : MonoBehaviour
{
    [SerializeField] private ARSession session;
    [SerializeField] private Text sessionStateText;

    private void Awake()
    {
        ARSession.stateChanged += OnARStateChanged;
    }

    IEnumerator Start()
    {
        if (ARSession.state == ARSessionState.None || ARSession.state == ARSessionState.CheckingAvailability)
            yield return ARSession.CheckAvailability();

        if (ARSession.state == ARSessionState.Unsupported)
            yield break;

        session.enabled = true;
    }

    private void OnARStateChanged(ARSessionStateChangedEventArgs args)
    {
        sessionStateText.text = args.state.ToString();
    }
}

ここまでできたら iOS アプリをビルドして実機で実行してみる．カメラが表示できて，Session の状態が SessionTracking になっていれば成功しているはず．

平面を検出して表示する

試しに平面を検出して表示してみる．

AR Foundation は何種類かの Trackable Managers を提供している．その中の AR Plane Manager を使うと，その名のとおり平面の検出ができる．

Plane Manager の Plane Prefab には任意の prefab を設定できるが，今回は出来合いの AR Default Plane を使う．GameObject > XR > AR Default Plane を一旦 scene に配置してから prefab 化し，prefab を Plane Manager に設定する．

検出された平面にポリゴンが表示されるようになる．

平面をタッチしてオブジェクトを置く

試しに適当なオブジェクトを平面の上に置いてみる．

いわゆる Raycasting が必要になるが，AR Foundation の提供する AR Raycast Manager を使えば簡単にできる． AR Raycast Manager を AR Session Origin にコンポーネントとして追加する． Raycast Prefab は任意なので None のままにする．

適当なクラスを作り，Raycast Manager を使って AR Plane との交点を検出し，そこに適当なオブジェクトを置いてみる．

public class AppController : MonoBehaviour
{
    [SerializeField] private ARRaycastManager raycastManager;
    [SerializeField] private GameObject arObjectPrefab;

    private readonly List<ARRaycastHit> _raycastHits = new List<ARRaycastHit>();

    private void Update()
    {
        if (Input.touchCount != 1) return;

        var touch = Input.GetTouch(0);
        if (touch.phase == TouchPhase.Ended)
        {
            if (raycastManager.Raycast(touch.position, _raycastHits, TrackableType.PlaneWithinPolygon))
            {
                var hit = _raycastHits.First();
                if (hit.trackable is ARPlane)
                {
                    Instantiate(arObjectPrefab, hit.pose.position, hit.pose.rotation);
                }
            }
        }
    }
}

少し注意するべき点としては，Raycast() するときに TrackableType.PlaneWithinPolygon を指定するようにする．デフォルトだと All になるようで，全ての平面が対象になるかつ Polygon に閉じない無限平面上で当たり判定されてしまう（違う，そうじゃない）．

3D モデルは Unity Asset Store から Low-Poly Simple Nature Pack を使わせてもらった．

まとめ・感想

Unity iOS で AR アプリ開発ことはじめとして，次のことをやってみた．

AR Foundation & ARKit をセットアップした
AR Plane Manager で平面検出し，デフォルトのビジュアライザで平面を表示した
AR Raycast Manager で AR Plane のどこをタッチしたのか判定した
タッチした場所に適当な 3D オブジェクトを表示した

AR Foundation によって AR を始めるための敷居はかなり低くなっている．一方で Plane Manager の精度はデフォルトだと驚きがある程は高くなく，エッジがずれていたり，10cm ぐらいの段差が丸められていたりする．もしかして LiDAR が有効になっていない？のは今後の課題とする．

部屋中に木をわさわさ生やすと楽しい．

:herb:

References

Unity iOS プロジェクトを Bitrise でビルドする

Wed, 06 Jan 2021 00:00:00 +0900

アプリ開発において CI が重要なのは Unity iOS プロジェクトでも同じだ．個人開発として趣味の範囲で細々とやっている身であっても，むしろであるからこそ，CI による自動化で作業リソースや集中力を節約したい．

今回の検証では，iOS/Android アプリ開発でよく使われる CI のひとつである Bitrise を使って Unity iOS プロジェクトをビルドする方法を考える．名もなき developer なので，Unity Personal ライセンスの有効化問題や Bitrise のビルド制限時間問題など「お金で解決できるはずの課題」が立ち塞がるが，強い気持ちと workaround でなんとかしていく．

概要

Ubuntu で Unity エディタを動かして Xcode プロジェクトを書き出す
Game CI が公開している Docker イメージを使うと便利
書き出したプロジェクトを macOS の workflow でビルドする
プロジェクトの受け渡しは Bitrise の Artifacts で行う

環境

Unity 2020.1.1f1
Docker 20.10.0
Bitrise Stacks
- Android & Docker, on Ubuntu 16.04 - LTS Stack
- Xcode 12.3.x, on macOS 10.15.5 (Catalina)

背景

Unity iOS プロジェクトをビルドしたい場合，CI の選択肢としては大きく分けて次の3つの方針がある．

セルフホスト（以下 Jenkins を想定）
Unity Cloud Build
その他 iOS 向け CI サービス

もちろん，それぞれについて利点と課題がある．

Jenkins

Jenkins は，ある意味最も便利な選択肢と言える． Worker のマシンを直接セットアップできるので Unity はもちろん，必要なソフトウェアを予めインストールしておくことも簡単だし，いざとなればマシンに直接ログインしてデバッグをすることもできる．一方で，セルフホストであることに伴うあれこれが，そのまま課題とも言える．

個人的にも以前は Jenkins を使って CI を構築していた．

Unity Cloud Build

Unity Cloud Build（以下 UCB）は，素直に一番簡単な選択肢だと思う． Unity Teams Advanced に$9/月を支払う必要があるが，Web の UI から必要最小限の設定で動かし始めることができる．個人的にもかれこれ1年以上使っているが，CI のメンテがほぼ不要なのでとても楽になった．

しかし，UCB に課題がないわけでもない． UI が微妙で使い難かったり，自動ビルドが自動でオフになったり，証明書の更新が面倒だったりと気になる点はあるが，なかでも一番気になるのはビルドに時間がかかることだ．ビルド時間はプロジェクト構成に依存するので結果の数字だけ話しても大した意味はないが，UCB だと Git リポジトリに push してからビルド完了通知が届くまで60分程かかっている．

このスピードだと commit 毎にビルドするのは現実的ではないので main ブランチ更新があったタイミングでビルドするようにしている．夜寝る前に feature ブランチをマージしておけば，翌朝には（運が良ければ）ビルドが配信されているはず…という感じで運用している．

Bitrise

その他 iOS 向け CI サービスは幾つかあるが，今回は Bitrise を対象とする．これは単にいつも使っているからという個人的な理由による．

利点としては，一言で言えば iOS 開発の現場で実際に使えるレベルの CI だということで，わざわざあれこれ挙げる必要はないだろう．Bitrise だと無料枠で macOS を使うことができる点も有難い．ただし，Unity iOS プロジェクトをビルドする場合に特有の問題として Unity エディタのライセンス有効化がある．

Unity ライセンス有効化問題

Unity エディタのライセンスを CLI から有効化する場合，Unity マニュアルの Command line arguments の定義に依れば -username と -password を渡せば良さそうに見えるが，実はこの方法で有効化できるのは有償のライセンスのみで，無料の Unity Personal ライセンスには対応していない．

では Personal ライセンスは CLI で有効化できないのかというと，実はできないこともない．手動のライセンス有効化（Manual Activation）という方法があって，次の手順で有効化できる．

ライセンス有効化ファイル（.alf）を Unity エディタから書き出す
Web ブラウザで Unity - Activation を開いてライセンスファイル（.ulf）を取得する
ライセンスファイル（.ulf）を Unity エディタに渡してライセンスを有効化する

手順2において手動によるアカウント認証が必要（アカウント設定によっては 2FA も必要）になるが，その前後の手順は CLI で実行できる．

ただし，この方法ではライセンスファイルが worker のマシン ID と紐づくので，毎回別の仮想マシンインスタンスを立ち上げる CI では，ビルドの度にマシン ID が変わってしまうため，ライセンスファイルを再利用することができないという問題がある．この問題について「Unity CI ALF」で検索すると，これまでも色々と試行錯誤されてきたことがわかる．主な方針としては仮想マシンの ID を固定するか，Puppeteer などを使ってライセンスファイル取得手順を自動化して毎回取得しなおすかになるが，macOS では前者の方針を取ることが難しい．

もし，Android など Linux でビルドできるプラットフォームが対象であれば，マシン ID を固定した Linux を使うことができる．では iOS を対象とする場合にはどうするか．

Ubuntu を使って Xcode プロジェクトを書き出す

というのが解決策となる（TL;DR）．

Unity エディタの CLI では -buildTarget を指定することで任意の Build Target に対して実行ファイルやプロジェクトを書き出すことができる．そして，実は iOS 用の Xcode プロジェクト（.xcodeproj）を書き出すことは Ubuntu の上で実行している Unity エディタでも可能となっている．なんとっ！

もちろん，書き出した Xcode プロジェクトから iOS アプリをビルドするためには Xcode とそれを動かすための macOS が必要となるが，Xcode プロジェクトを書き出すまでであれば Ubuntu でも可能だ．つまり，ビルドの workflow を次のように分割すれば良い．

Unity エディタから Xcode プロジェクトを書き出す（on Ubuntu）
Xcode プロジェクトから .ipa をビルドする（on macOS）

Unity のライセンスが必要になるのは手順1のみなので，macOS で Unity ライセンスを有効化できない問題は問題にならない． Xcode プロジェクトが書き出せてしまえば，後は基本的には通常の iOS アプリのビルドと変わらないので，特に難しいところもない．

先行事例

有志による GameCI というプロジェクトがある． Unity のライセンス有効化やプロジェクトのビルドを行うスクリプトを公開している． Unity エディタをインストールした Ubuntu ベースの Dockerfile や Docker イメージも提供されている．

対象とする CI サービスについては GitHub Actions や Travis CI などの説明があるが，今回対象とする Bitrise については記述が無かった．また，Xcode プロジェクトから iOS アプリをビルドする方法についても具体的に説明が無かった．そこで，今回の検証では次の点について新たに考えて補足する．

Bitrise で Unity iOS プロジェクトをビルドする
Bitrise の複数 workflow 間で artifact を共有する
Unity iOS の Xcode プロジェクトから .ipa をビルドするときの注意点

以上で背景説明は終わり．

技術構成

Bitrise

今回の検証の中心． Stack は次の2つを使う．

Android & Docker, on Ubuntu 16.04 - LTS Stack
Xcode 12.3.x, on macOS 10.15.5 (Catalina)

Workflow と stack は 1:1 になるので，Xcode プロジェクト書き出し用と Xcode ビルド用で workflow を分けて，前段の workflow から後続の workflow をトリガーする形になる． Workflow を分割せずに，macOS の stack で Docker を動かして Ubuntu を起動する方法もありそうだが，次の2つの理由により Ubuntu stack を使うことにした．

デフォルトの macOS stack には，Docker がインストールされていない
ビルド時間が伸びると workflow の制限時間内にビルドが終わらない可能性がある

特に，制限時間については Free プランでは30分と短めなので，少し気を付ける必要がある．

Unity エディタ on Ubuntu

Unity エディタをインストールした Ubuntu マシンを用意する．簡単のため GameCI プロジェクトが提供している Docker イメージを使う．

なお，Dockerfile も GitHub の GameCI で公開されているので，自前で Docker イメージを用意したり，そもそも Docker を使わずに Ubuntu を直接セットアップすることも可能．

Bitrise Artifacts

分割した workflows 間で Xcode プロジェクトを受け渡すために Bitrise Artifacts の仕組みを使う．

後続の workflow では，Bitrise API を使って artifacts をダウンロードする形で Xcode プロジェクトを受け取る．

ライセンス有効化ファイルの書き出し

まずは Unity エディタからライセンスファイルを書き出す．基本的には1回実行すれば良いものなので，個別の Workflow として構築しておく． Docker を使うので Ubuntu の stack を使う．

GameCI 提供の Docker イメージが Docker Hub にあるので，そちらから pull して使う．Tags 一覧の ios モジュールを含むものから自分のプロジェクトに合ったバージョンを選んで，Env Vars に UNITY_DOCKER_TAG として設定しておく．

ビルドスクリプトは大した量でもないので Workflow に Script ステップを追加して書いてしまう． Unity を batch モードで起動して，書き出された .alf ファイルのパスを環境変数に書き込む．なお，unity-editor というのは GameCI の Docker イメージに設定されている bash スクリプトで，UnityEditor を batch モードで xvfb-run してくれるラッパーになっている．詳しくは GitHub にある Dockerfile を見れば分かる．

#!/usr/bin/env bash set -x docker pull unityci/editor:$UNITY_DOCKER_TAG docker run --rm -v $PWD:/build -w /build unityci/editor:$UNITY_DOCKER_TAG \ bash -c "unity-editor -nographics -logFile /dev/stdout -quit -createManualActivationFile" UNITY_EXIT_CODE=$? UNITY_ALF=$(find $PWD -name "*.alf" -print -quit) if [[ -n "$UNITY_ALF" ]]; then envman add --key UNITY_ALF --value "$UNITY_ALF" echo "Open https://license.unity3d.com/manual and get License file (.ulf)" else echo "License activation file (.alf) is not found" exit $UNITY_EXIT_CODE fi

後続の Deploy to Bitrise.io ステップを使って .alf ファイルを Bitrise に artifact としてアップロードする．

Workflow を実行して，実行結果のページから .alf ファイルを手動でダウンロードして，Unity - Activation を開き，Unity アカウントで認証してライセンスファイル（.ulf）を取得する．取得したライセンスファイルを Code Signing の Generic File Storage に ID: UNITY_LICENSE_FILE としてアップロードしておく．

Xcode プロジェクトの書き出し

Unity エディタから Xcode プロジェクトを書き出す．こちらも Docker を使うので Ubuntu の stack を使う．

ライセンスファイルを復元して，Unity CLI に渡してエディタを有効化する．

肝心の Xcode プロジェクトの書き出しは，いつもどおり batch モードを使うだけで特に難しいところはない．引数は最小限のものだけ渡しているが，いつもどおり Command line arguments から必要なものを使えば良い．

#!/usr/bin/env bash set -x UNITY_ULF=Unity_vX.ulf curl $BITRISEIO_UNITY_LICENSE_FILE_URL | tr -d '\r' > $UNITY_ULF if [[ -z "$PROJECT_PATH" ]]; then PROJECT_SETTINGS_PATH=$(find . -name "ProjectSettings" -print -quit) PROJECT_PATH=$(dirname "$PROJECT_SETTINGS_PATH") fi docker pull unityci/editor:$UNITY_DOCKER_TAG docker run --rm -v $PWD:/build -w /build unityci/editor:$UNITY_DOCKER_TAG \ bash -c " unity-editor -nographics -logFile /dev/stdout -quit \ -manualLicenseFile $UNITY_ULF; unity-editor -nograhpics -logFile /dev/stdout -quit \ -projectPath $PROJECT_PATH \ -buildTarget iOS \ -executeMethod $EXECUTE_METHOD; UNITY_EXIT_CODE=\$?; find . -type l -exec bash -c 'cp --remove-destination \$(readlink {}) {}' \; ; exit \$UNITY_EXIT_CODE; " UNITY_EXIT_CODE=$? XCODE_PROJECT_PATH=$(find $PWD -name "Unity-iPhone.xcodeproj" -print -quit) if [[ -z "XCODE_PROJECT_PATH" ]]; then echo "Xcode project is not found" exit $UNITY_EXIT_CODE fi BUILD_DIR=$(dirname $XCODE_PROJECT_PATH) envman add --key BUILD_DIR --value "$BUILD_DIR"

地味に重要なのが find -type l -exec しているところ．ビルドした Xcode プロジェクトが入ったディレクトリをまるっと artifact にアップロードしたいので，symlink を解決して実際のファイルに差し替えている． Symlink のままだと artifact の中に実際のファイルは含まれないため，後続の macOS を使った workflow でビルドするときにファイルを見つけられずリンカエラーになってしまう．

ということで，再び Deploy to Bitrise.io ステップを使って $BUILD_DIR をまるっとアップロードする．ディレクトリを Zip してアップロードするオプションがあるので true にしておくこと．

アップロードした artifact を後続の workflow に渡すために，ダウンロード URL を取得して workflow に引数として渡したい． Bitrise の API ドキュメントを参照すると GET リクエストで artifact の情報を JSON で取得できることが分かる． Artifact を指定するための slug は Deploy ステップが出力する $BITRISE_PERMANENT_DOWNLOAD_URL_MAP から雑に抜き出す．

実際の artifact ファイルをダウンロードできる URL は JSON の中に記録されているが，expiring_download_url という名前のとおり有効期限付きの URL になっているので，実際にファイルをダウンロードする直前に JSON を取得するのが良い．

#!/usr/bin/env bash set -x -e ARTIFACT_SLUG=$(echo $BITRISE_PERMANENT_DOWNLOAD_URL_MAP | sed 's/^.*artifact\/$.*$\/download.*$/\1/') ARTIFACT_URL="https://api.bitrise.io/v0.1/apps/$BITRISE_APP_SLUG/builds/$BITRISE_BUILD_SLUG/artifacts/$ARTIFACT_SLUG" envman add --key ARTIFACT_URL --value "$ARTIFACT_URL"

GET リクエストを送る先の URL を ARTIFACT_URL に設定して，後続の workflow の入力として渡す． Workflow の実行は Trigger Bitrise workflow ステップを使えば良い． Workflow をトリガーするためのトークンは Bitrise アプリの Code タブから取得できる．

Xcode プロジェクトのビルド

最後に Xcode プロジェクトから iOS アプリをビルドする．

Artifact のダウンロード URL を取得して，Zip ファイルをダウンロードして，Zip を展開する． Bitrise API を叩くための API トークンが必要なので，Account Settings ページで生成して，Secrets の BITRISE_API_TOKEN に設定したものを読んでいる．

#!/usr/bin/env bash set -e -x ARTIFACT_DOWNLOAD_URL=$(curl -H "Authorization: token $BITRISE_API_TOKEN" "$ARTIFACT_URL" | jq -j ".data.expiring_download_url") curl -o Build.zip $ARTIFACT_DOWNLOAD_URL mkdir Build unzip Build.zip -d Build

ここまでできれば，あとは通常の iOS アプリのビルドと変わらないので要点だけ補足する．少し気を付ける必要があった点は次のとおり．

CocoaPods に時間がかかる問題

CocoaPods が必要なプロジェクト（Firebase SDK を使っているなど）の場合，Xcode プロジェクト書き出しを Ubuntu で行っているため，Unity の PostProcessBuild では pod install に失敗しているはずなので，macOS 側で xcodebuild する前に実行しておく．なお，Firebase SDK が生成する Podfile の source が GitHub を参照していて pod install にかなーり時間がかかるため，source の URL には CDN を使うように書き換えておくと時間を短縮できる．

Xcode アーカイブに時間がかかる問題

ひとまず Bitcode のオプションを切って短縮した．ただし，これだと App Store 版がビルドできなくなるので，それは今後の課題とする．なお，お金を払うという最強のソリューションが（以下略）

最後に Slack に通知して完了．

まとめ・感想

Unity iOS プロジェクトを Bitrise でビルドすることができた．

Game CI プロジェクトが提供する Docker イメージを使った
Ubuntu を使うことで Unity Personal ライセンスでも CI の上で Unity を動かすことができた
iOS アプリのビルドは Workflow を分割して実装した
- Ubuntu で Unity エディタから Xcode プロジェクトを書き出した
- macOS で Xcode プロジェクトから iOS アプリをビルドした

肝心のビルド時間については，Bitrise だと30分強くらいで完了しているので，40-50% 程度は短縮できている．ただし，CI を構築できるまでに Unity Cloud Build の100倍ぐらい試行錯誤しているのは忘れることにする．

:doughnut:

References

Apple Developer 登録端末の大掃除

Sun, 20 Dec 2020 00:00:00 +0900

この記事は Goodpatch Advent Calendar 2020 の20日目です．

年末が近づいているということで，どこの会社でもどこのご家庭でも一年間溜まったアレの片付けに追われているのではないでしょうか．そうです Apple Developer に登録した端末一覧です．今年の端末は今年の内に．新年を清々しい気持ちで迎えるぞ．

概要

Apple Developer に登録している古くなった端末を削除したい
Swift Package Manager を使ってコマンドラインツールを作る
端末の操作は App Store Connect API で行う
- 端末の一覧を取得する
- 古くなった端末を Disabled にする（削除はできない仕様）

コードは GitHub にあります．

環境

Swift 5.3.1
App Store Connect API v1

Apple Developer 管理画面における端末管理

iOS アプリを自由にインストールできる端末は開発者ライセンスと証明書によって制限されています．その中で，比較的制約条件が少ない Ad Hoc 方式を使いたい場合，Apple Developer にインストール対象端末をひとつひとつ登録する必要があります．

端末の UDID を集めて登録するのは一手間かかる作業ですが，多くの鍛えられた iOS Developer はこの手間に慣れっこです． UDID 確認方法の手順書を用意していたり，Firebase App Distribution など 3rd パーティ製のインフラに乗るようにしていたり，既に解決手段を持っていると思います．

それでは，ここで登録した端末はその後どうなっているでしょうか？

個人の経験や想像でしかありませんが，多くの場合「そのまま放置されている」のではないでしょうか．年に一回の開発者ライセンス更新タイミングで，Apple から登録端末リセットの機会を与えられたものの，端末一覧を見ただけではどれがリセットして良い端末かは判断できないのが実情だと思います．とどのつまり，削除を諦めて「現状維持」とするか，強い気持ちとマナコストを支払って「全体除去」を唱えるかといった選択肢しかありません．

App Store Connect API

それでは「もう少し良い方法はないのか？」というと，なくはないです．

Apple は App Sotre Connect API の提供を WWDC 2018 で発表しました．この API を使うことで，開発者は Apple Developer アカウントや App Store Connect の管理項目をプログラムから変更できるようになります．

API の使い方については公式ドキュメントに詳しくあるとおりですが，その中でも Devices の使い方を調べてみると，API を使えば各端末について以下のようなプロパティが取得できることが分かります．

Name	Type	Note
deviceClass	string	Possible values: APPLE_WATCH, IPAD, IPHONE, IPOD, APPLE_TV, MAC
model	string
name	string
platform	BundleIdPlatform	Possible values: IOS, MAC_OS
status	string	Possible values: ENABLED, DISABLED
udid	string
addedDate	date-time

参考：Device.Attributes | Apple Developer Documentation

ここで，端末管理のために特に使えそうなものが addedDate です．他のプロパティは管理画面の一覧や詳細を見れば確認することができるのですが，なぜか端末の登録日を管理画面から知ることはできません．

端末の登録日が分かれば，例えば端末管理ルールとして「登録から2年以上経過している端末は削除する」といったものを考えることができそうです．

なお，端末のモデルを使ってルールを決めることもできそうですが，端末を積極的に削除することができなかったり，あえて古めの端末を登録している場合を考慮できなかったりといった問題がありそうです．例えば2020年末時点で iOS 13.x までしかサポートしなくて良いとした場合でも，iPhone 6s 以降の端末については使われている可能性が残ります．端末一覧にリストされているその iPhone 6s は既に数年前から使われていない端末かもしれませんし，つい数ヶ月前にテスト用に登録した端末かもしれません．

今回の検証では「登録から〇〇以上経過している端末は削除する」のルールを考え，これを API を使って自動で運用する方法を検証します．

技術構成

今回の検証では技術構成を次のように考えました．

App Store Connect API

既に説明したとおりです．公式ドキュメントの Topics > Essentials を読んでいけば特に難しいことはないと思います．

Swift

基本的には App Store Connect API を叩くだけなので，プログラミング言語は好きなものを使えば良さそうです．今回は Apple のお膝元ということで Swift を使ってみます． API を叩くために有志によって開発されている OSS のラッパーを使うこともできますが，それではネタがなくなりそうなので自前で書くことにします．

Swift Argument Parser

Swift でコマンドラインツールを作りたいわけですが，コマンドライン引数をパースすることは地味に面倒なので Apple が公開している Swift Argument Parser を使います． Protocol 準拠した struct を定義すれば引数やオプションを簡単にパースでき，さらに help オプションまで用意してくるのでとても便利です．

JWTKit

App Store Connect API は JSON Web Tokens（JWT）による認証を要求します． JWT の header や payload の構造は自前で定義しますが，それを JWT にエンコードする処理はライブラリに任せることにします．今回は Vapor プロジェクトでも使われている JWTKit を採用します．

プロジェクトを作る

Swift Package Manager を使ってプロジェクトを作ります．まずは swift コマンドで雛形に従ったプロジェクトを作ります．

$ mkdir apple-device-manager
$ cd apple-device-manager
$ swift package init --type executable

Creating executable package: apple-device-manager
Creating Package.swift
Creating README.md
Creating .gitignore
Creating Sources/
Creating Sources/apple-device-manager/main.swift
Creating Tests/
Creating Tests/LinuxMain.swift
Creating Tests/apple-device-managerTests/
Creating Tests/apple-device-managerTests/apple_device_managerTests.swift
Creating Tests/apple-device-managerTests/XCTestManifests.swift

続いて，今回使用するパッケージを Package.swift ファイルに追記します． Package.swift ファイルを Xcode で開くと Xcode Workspace が作られるので，以降の編集作業はそちらで進めます．

// swift-tools-version:5.3

import PackageDescription

let package = Package(
    name: "apple-device-manager",
    platforms: [
        .macOS(.v10_15),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser", from: "0.3.1"),
        .package(url: "https://github.com/vapor/jwt-kit.git", from: "4.0.0")
    ],
    targets: [
        .target(
            name: "apple-device-manager",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "JWTKit", package: "jwt-kit")
            ]),
        .testTarget(
            name: "apple-device-managerTests",
            dependencies: ["apple-device-manager"]),
    ]
)

Package.swift を更新して保存すると，Xcode は自動でパッケージのインストールを開始します．

インストールが完了した後，Xcode からプログラムを実行（Run）すると Console にメッセージが表示されるはずです．

Hello, world!
Program ended with exit code: 0

認証する

API の認証を通過するためには，API トークンが必要です．まず Apple Developer 管理画面で App Store Connect の API キーを作る手順に従って API キー（.p8）を作ります．さらにその API キーを元に API トークンを生成すると実際の HTTP リクエストで使うトークン（JWT）を得ることができます．

App Store Connect API の仕様で，トークンの有効期限は20分以内に設定する必要があるため，トークンは適宜作り直す必要があります．キーの id，issuerId，value（値そのもの）を入力として，JWT にエンコードされたトークンを出力してみます．

import Foundation

struct APIKey {
    let id: String
    let issuerId: String
    let value: String
}

import Foundation
import JWTKit

struct APIToken {
    let value: String
    let expiration: Date

    struct Payload: JWTPayload {
        /// Your issuer ID from the API Keys page in App Store Connect (Ex: 57246542-96fe-1a63-e053-0824d011072a)
        var iss: IssuerClaim

        /// The token's expiration time, in Unix epoch time; tokens that expire more than 20 minutes in the future are not valid (Ex: 1528408800)
        var exp: ExpirationClaim

        var aud: AudienceClaim = .init(value: "appstoreconnect-v1")

        func verify(using signer: JWTSigner) throws {
            try self.exp.verifyNotExpired()
        }
    }

    static func encode(_ key: APIKey) throws -> APIToken {
        let expiration = Date().addingTimeInterval(20 * 60)
        let payload = Payload(iss: .init(value: key.issuerId), exp: .init(value: expiration))
        let signer = try JWTSigner.es256(key: .private(pem: key.value))
        let jwt = try signer.sign(payload, kid: .init(string: key.id))

        return APIToken(value: jwt, expiration: expiration)
    }
}

試しに Swift のコードを実行して API トークンを生成して出力してみます．

import Foundation

let keyId = "XXXXXXXXXX"
let keyIssuerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
let keyFilePath = "/full/path/to/AuthKey_XXXXXXXXXX.p8"

let keyValue = try String(contentsOfFile: keyFilePath)

let key = APIKey(id: keyId, issuerId: keyIssuerId, value: keyValue)
let token = try APIToken.encode(key)

print(token.value)

xxxxxx.xxxxxxxxxxxxx.xxxxxxxx
Program ended with exit code: 0

得られたトークンを使って curl でリクエストを投げてみます．端末の一覧が JSON 形式で取得できれば成功です．

$ curl https://api.appstoreconnect.apple.com/v1/devices \
      -H 'Authorization: Bearer xxxxxx.xxxxxxxxxxxxx.xxxxxxxx'

{
  "data" : [ {
    "type" : "devices",
    "id" : "xxxxxxxxxx",
    "attributes" : {
      "addedDate" : "yyyy-MM-ddTHH:mm:ss.000+0000",
      "name" : "xxxx",
      "deviceClass" : "IPHONE",
      "model" : null,
      "udid" : "xxxxxxxx-xxxxxxxxxxxxxxxx",
      "platform" : "IOS",
      "status" : "ENABLED"
    },
    "links" : {
      "self" : "https://api.appstoreconnect.apple.com/v1/devices/xxxxxxxxxx"
    }
  }, {
    /* ... */
  } ],
  "links" : {
    "self" : "https://api.appstoreconnect.apple.com/v1/devices"
  },
  "meta" : {
    "paging" : {
      "total" : 5,
      "limit" : 20
    }
  }
}

コマンドライン引数から入力を受け取る

前述どおり Swift Argument Parser を使います．

README が充実しているので特に説明することはありませんが，Subcommands や ParsableArguments を使うとコマンドを簡単に構造化できます．ここでは adm list で端末リストを出力するようなコマンドを考えました．

struct AppleDeviceManager: ParsableCommand {
    static var configuration = CommandConfiguration(
        commandName: "adm",
        abstract: "Apple Device Manager",
        subcommands: [List.self]
    )
}

extension AppleDeviceManager {
    struct Options: ParsableArguments {
        @Option(help: "Path to the private key.", completion: .file(extensions: [".p8"]))
        var keyPath: String

        @Option(help: "Id of the private key.")
        var keyId: String

        @Option(help: "Id of the issuer of private key.")
        var issuerId: String
    }

    struct List: ParsableCommand {
        @OptionGroup var baseOptions: Options

        mutating func run() throws {
          // Do something
        }
    }
}

AppleDeviceManager.main()

コマンドライン引数やオプションの parse は煩雑になりがちですが，Swift Argument Parser を使うと簡単に可読性高いコードで記述することができ，ひとことで言うとめっちゃ良いです．

端末一覧を取得する

正直なところ，API トークンを得られた後は普通に API を叩くだけの簡単なお仕事なので特に説明するところがありません．

リクエストやレスポンスは APIKit で型付けしています．レスポンスが返ってくるまでコマンドをサスペンドしておく必要があるので，DispatchSemaphore を使って wait しています． APIKit の Session.send のコールバックは sessionQueue にしておかないと semaphore.signal() が発火しないので注意します．

struct List: ParsableCommand {
    @OptionGroup var baseOptions: Options

    mutating func run() throws {
        let key = try baseOptions.getKey()
        let token = try APIToken.encode(key)

        let semaphore = DispatchSemaphore(value: 0)
        Session.send(GetDeivcesRequest(token: token), callbackQueue: .sessionQueue) { result in
            switch result {
                case .success(let response):
                    DevicePrinter().print(response.data)
                    semaphore.signal()
                case .failure(let error):
                    AppleDeviceManager.exit(withError: error)
            }
        }
        semaphore.wait()
    }
}

端末のステータスを更新する

API には登録済み端末を編集するエンドポイントが用意されているので，これを使って端末のステータスを DISABLED に更新します．簡単なお仕事なので（以下略）．

コマンドをビルドする

ビルドコマンド swift build を実行してバイナリを書き出します．書き出しに成功したら，適当に PATH が通っているところに移動して実行します．

$ swift build --configuration release
$ cp .build/release/apple-device-manager /usr/local/bin/adm

# Swift Argument Parser が生成してくれる help を見る
$ adm --help

OVERVIEW: Apple Device Manager

USAGE: adm <subcommand>

OPTIONS:
  -h, --help              Show help information.

SUBCOMMANDS:
  list
  disable

  See 'adm help <subcommand>' for detailed help.

# 端末一覧を表示する
$ adm list --key-id=xxxx --issuer-id=xxxx --key-path=/xxx/xxx/xxxx.p8

XXXXXXXXXX E 2020-07-12 10:22:31 +0000 "iPhone SE"
XXXXXXXXXX E 2019-10-30 13:30:12 +0000 "Xxxxxxxx - iPhone X"
XXXXXXXXXX E 2020-04-20 00:44:59 +0000 "Xxxxxxxx - iPhone 8 Plus"
XXXXXXXXXX E 2020-04-29 11:28:08 +0000 "Xxxxxxxx - iPhone 11 Pro"
XXXXXXXXXX E 2019-10-30 14:08:55 +0000 "Xxxxx - iPhone X"

# 登録から1年以上経過している端末は Disabled にする
$ adm disable --age=1 --key-id=xxxx --issuer-id=xxxx --key-path=/xxx/xxx/xxxx.p8

XXXXXXXXXX D 2019-10-30 13:30:12 +0000 "Xxxxxxxx - iPhone X"
XXXXXXXXXX D 2019-10-30 14:08:55 +0000 "Xxxxx - iPhone X"

という感じで，Apple Developer に登録している端末に対して，コマンドラインツールを用いて削除する（フラグを立てる）ことができるようになりました．あとは好きな CI に乗せて定期的に実行すれば良さそうです．なお，GitHub Actions だとビルド時間が気になるかな？と思いましたが杞憂でした．私の mac 遅すぎ．

まとめ

Apple Developer に登録している端末が放置されている問題（仮説）に対して，古い端末を自動で削除する（フラグを立てる）方法を検証しました．

App Store Connect API で端末一覧を取得することや，端末のプロパティを編集することができた
Swift Argument Parser はめちゃくちゃ便利だった
ただし Swift で書くのが楽かというと…うーん

なにはともあれ，今年もあと10日ほど．端末の掃除も終わった（？）ということで来年も良い年になりますように．

Goodpatch Advent Calendar 2020 はもう少しだけ続きます．

:sunrise:

One More Thing

Linux 用にビルドする

今回は Swift Package Manager でプロジェクトを作りました．つまり Linux 用にもビルドできるのでは？ということで，Docker を使って Linux 用のバイナリを書き出します．

Docker Image については Vapor プロジェクトでも使われている Swift 公式の Docker Image を使えば良さそうです．適当に pull して run してビルドします．

$ docker pull swift:5.3-focal
$ docker run --rm -it -v $PWD:/adm -w /adm swift:5.3-focal swift build --configuration release

がしかし，ここでビルドエラーになります．やはり Write once, run anywhere とはいかないようです．

URLSession が解決できない問題を解決する

Linux の場合 URLSession や URLRequest などは FoundationNetworking という別モジュールから読む必要があるようです．そこで，コンパイラディレクティブを使って，Linux の場合のみ FoundationNetworking を import します．

import Foundation
#if os(Linux)
import FoundationNetworking
#endif

本編では APIKit を使っていましたが，同様のエラーが APIKit の内部でも出ます．ということで一旦 APIKit を使うことを諦めることにします．かと言っていまさらコードを書き換えるのも面倒なので，適当にパッチを書いてコンパイルを通しました．

$ docker run --rm -it -v $PWD:/adm -w /adm swift:5.3-focal swift build --configuration release
$ docker run --rm -it -v $PWD:/adm -w /adm swift:5.3-focal .build/release/apple-device-manager --help

OVERVIEW: Apple Device Manager

USAGE: adm <subcommand> # 以下略

Linux 向けにビルドするつもりなら，ライブラリを選ぶときは少し気をつけたほうが良さそう．

:memo:

参考

Abstract API を使った CI の構成を考える

Sun, 06 Dec 2020 00:00:00 +0900

この記事は Goodpatch Advent Calendar 2020 の6日目です．

モバイルアプリの UI デザインツールとして Sketch はデファクトと言っても良いくらい広く使われるようになりました．それに伴って Sketch の利用を前提としたデザインコラボレーションの手段を提供する Abstract のようなサービスも現れました．

Sketch や Abstract は基本的には GUI での利用を前提としたツールですが，それぞれ CLI ツールや Web API も提供しています．今回はこれらを利用した UI デザインのポストプロセス自動化について考えます．

…考えます．そうです「考える」だけなのです．ブラウザの戻るは Cmd + [ です．

概要

プログラミングの観点で UI デザインワークフローの効率化を考える
CI による自動化を考える
Abstract を中心とした CI の構成を考える

なお，文中で補足しますが，ここでいう「UI デザイン」はかなり狭義な範囲を指しています．

プログラミングの観点で UI デザインのワークフローの効率化を考える

プログラミングのワークフロー

近年のモバイルアプリ開発において，プログラミングのワークフローはおおよそベストプラクティスと呼べるものが定まっていると思います．もちろん，各々のプロジェクトの意向によって構成は様々だと思いますが，例えば以下のようなワークフローを組んでいるのプロジェクトは多いのではないでしょうか．

Git-flow に従い，作業ブランチを作って実装を進める
実装が完了したら GitHub で Pull Request を提出する
Pull Request でコードレビューを受ける
CI による自動テストを通過する
レビュアーからの承認を得る
Pull Request をマージする
CI によって自動でビルドが作成される

特に，コードの品質を保つためのレビューや作業効率化のための自動化は，アジャイルな開発スタイルでは欠かせない要素となっています．

さらに，ワークフローの中でも「実装」部分に着目すると，ここでも作業効率化のために様々な仕組みを使うことが当たり前となっていると思います．

テキストエディタの機能を使ってコードの補完や自動編集を行うこと
Linter などの静的解析ツールを使って機械的に検出可能なミスを減らすこと
ユニットテストを用意して回帰テストを行うこと
さらには TDD のようにテストによって製品コードの設計の質を上げること

ワークフローを定めたり様々なレイヤーで効率化を行うことで，エンジニアはエンジニアが本当に注力すべきクリエイティブな仕事に集中できます．

UI デザインのワークフロー

それでは，プログラミングのワークフローと比較して UI デザインのワークフローはどうなっているでしょうか．ただし，ひとまとめに「UI デザイン」と言ってしまうととても話をまとめきれないほど大きな概念なので，ここでは上記のプログラミングのワークフローに相当する部分についてのみ考え，それを狭義の「UI デザイン」と呼ぶことにします．

プログラミングのワークフローで挙げた項目それぞれに相当するものを考えると，例えば以下のようなフローが考えられます． Abstract のようなツールの登場により，プログラミングと同じようなフローが組めるようになっています．

プログラミング	UI デザイン
作業ブランチ	Abstract でブランチを作ることができる
Pull Request を提出する	ブランチ単位で Review に出すことができる
コードレビュー	Review の上でコメントをすることができる
CI による自動テスト	？？？
レビュアーからの承認	Review の上で承認を得ることができる
Pull Request のマージ	ブランチを Master にマージする
CI による自動ビルド	？？？

こうして比較すると，Abstract や Sketch を As-Is の範疇で使うと考えた場合，自動化の観点が抜けているのではないか？ということに気付きます．

わざわざ「As-Is で」と書いたのは，これらの点についてツールの開発者は既に考慮していて，Abstract には Web API が，Sketch には sketchtool という CLI ツールが提供されているためです．プロジェクトに合わせて CI を組んだりコードを書いたりする必要がありますが，自動化するために必要なツールは揃っている状況です．

続いて，ワークフローの中で「実装」に相当するような，Sketch ファイルの編集作業について比較してみます．

プログラミング	UI デザイン
コードの補完や自動編集	サードパーティ製の Sketch プラグインで検索や置換などが可能
静的解析ツール	？？？（Assistants を利用可能）
回帰テスト	？？？
テストによって製品コードの設計の質を上げる	？？？

プログラミングの場合と比較すると，UI デザインの効率化はかなり遅れているように感じます．ただし，これはあくまでプログラミングのフローを元に一方的な視点で比較しているので，恣意的でかなりアンフェアな比較です．それでも，現状多くのプロジェクトにおいて Sketch ファイルを「きれいに」保つのは，UI デザイナの注意力に頼っている状況であると感じている人も多いのではないでしょうか．

なお，2020年8月から Sketch では Assistants という機能を使えるようになりました． Assistants については今回検証しませんが，静的解析による効率化が期待できる機能です．

CI による自動化

それではプログラムの力を使って Sketch ファイルに対する単純作業を自動化できないでしょうか？例えば「CI による自動ビルド」に相当するような作業を Sketch に対して行えるでしょうか？

実は CI に sketchtool を組み込むというアイデア自体は，既に数年前から各所で事例が共有されています．例えば iOSDC Japan 2017 ではアイコンや画像の配置をCIで自動化するという発表があり，CI と sketchtool を使って iOS の Asset Catalog を書き出して GitHub に Pull Request を出すまでを自動化したとあります（より詳しくは Konifar’s WIP を参照）．

ただし，これらの事例は Git を中心としたエンジニア寄りのワークフローになっています． Git を使うこと自体は CI の組みやすさという点でメリットもあり，また，デザイナーが Git を使う障壁も GUI ツールを使えばそこまで高くない（個人の経験）ですが，Abstract を使っているフローの中で「Git リポジトリにも push してください」というのは明らかに面倒です．

よって Abstract API を使えば Git の場合と同様に CI を組めるのではないか？というのが今回の検証内容となります．ようやく少し技術ブログらしい感じになってきました．

Abstract を中心とした CI の構成

Abstract を中心とした CI の構成を考えます．基本的には Git を中心とした構成と変わらず，Sketch ファイル更新の検知と Sketch ファイルの取得を Abstract 経由に置き換える形です．

デザイナーが Abstract の Master ブランチを更新する
Master ブランチの更新を検知する
Master ブランチから Sketch ファイルを取得する
Sketch ファイルからアセットを書き出す
Google Drive にデプロイする

上記は自分のプロジェクト環境に合わせて組んでみた構成ですが，もちろんアセットの出力内容や出力先を変えることは自由にできます．また，それらステップ 4-5 については既存の事例を Web で見つけることができるので，今回は説明しません．

Abstract API

今回の検証の主な対象である Abstract 公式の API です． API の仕様については Abstract SDK API Reference にまとまっています． SDK が提供されているので，それを使って API を叩く形になります．

SDK は npm パッケージとして提供されていて TypeScript で使うことができます． API トークンはプロジェクトに対する Viewer 権限があれば発行できるようなので，比較的簡単に使い始めることができます．

API でできること

詳細については API Reference を参照するとして，例えば以下のようなことができます．

API	できること
`client.branches.list(...)`	ブランチの一覧を取得する．
`client.files.raw(...)`	任意の Sketch ファイルを取得する．
`client.previews.raw(...)`	任意の Layer を png として書き出す．なお svg や pdf には非対応．

少なくともこれだけできれば，ブランチに更新があるか調べて，更新があった場合には Sketch ファイルを書き出すといったことが可能です．

Webhooks について

更新を push 型で受け取る仕組みとして Abstract は Webhooks を提供しているようです．ただし Webhooks の機能は2020年11月時点では beta となっています．実は今回の検証のために Request beta access now から何度かリクエストを送ったのですが，残念ながら返答がありませんでした．

Webhooks が使えないので，検証では Crontab による定期トリガーを設定しました．トリガーさえしてしまえば pull 型の差分チェックはできるのでヨシ！とします．（嘘です．Webhooks 使いたいです．よろしくお願いします…）

Sketch ファイルを書き出す

Abstract のファイル構造としては，組織（Organization）> プロジェクト（Projects） > Sketch ファイル（Files）という形になっています．また，ブランチについては，プロジェクト > ブランチ（Branches）という形でプロジェクトに紐づきます．したがって，最初に API トークンと Organization ID さえ分かっていれば，あとはトップダウンでクエリしていくことができます．

以下のコードは実際のコードではなく説明用に簡略化したコードですが，Sketch ファイルを書き出すまでの流れはおおよそ把握できるかと思います．

import * as abstract from 'abstract-sdk';

async function main() {
  const client = new abstract.Client({ accessToken: process.env.ABSTRACT_API_TOKEN });
  const organization = { organizationId: process.env.ABSTRACT_ORGANIZATION_ID };

  const projects = await client.projects.list(organization);
  const project = projects.find(x => x.name === 'GR@DATE WING') || process.exit(1);

  // Master ブランチの ID は 'master' と決まっている．
  const branches = await client.branches.list({ projectId: project.id });
  const master = branches.find(x => x.id === 'master') || process.exit(1);

  const headCache = /* ... */ ;
  if (master.head === headCache) process.exit(0);

  // 最新コミットの SHA は 'latest' でクエリできる．
  const baseQuery = { projectId: project.id, branchId: master.id, sha: 'latest' };
  const files = await client.files.list(baseQuery);

  for (const file of files) {
    const fileQuery = { ...baseQuery, fileId: file.id };
    await client.files.raw(fileQuery, { filename: `${file.name}.sketch` });
  }
}

実際のコードでは head の差分比較を別スクリプトとして分離したり，書き出す Sketch ファイルの条件を設定ファイルで指定できるようにしたり，といった考慮がされています．実際のプロジェクトだと「アイデア置き場」としての Sketch ファイルなど，書き出す必要のない中間成果物もあるためです（まさにスケッチ！）．

sketchtool のインストール

Sketch ファイルが取得できたので，あとは sketchtool をインストールすればアセットを書き出すことができます．

インストールからアセット書き出しまでの手順は前述の iOSDC トークに関連する GitHub リポジトリなどに詳しく紹介があります．ただし，Sketch の ZIP ファイルのダウンロード URL が古くなっているようで，新しい URL は次のとおりでした．

https://download.sketch.com/sketch.zip

ちなみに，ファイルのダウンロードや Unzip などはシェルのコマンドで実行する方が楽なので，Node.js から child_process.exec() を呼びまくるという，やや強引な方法で実装しました．いっそのことシェルスクリプトの方が良いかもしれません．

import { promisify } from 'util';
import * as child_process from 'child_process';

async function main() {
  const exec = promisify(child_process.exec);
  await exec(`curl -L -o sketch.zip https://download.sketch.com/sketch.zip`);
  // ...
}

その他の技術的要素

その他の技術的要素について，ひとことふたこと説明しておきます．

Google Drive へのアップロードは Google Drive API Reference を参照すれば，少々面倒なことはあっても難しいことはないと思います．なお2020年11月時点で最新版の V3 を使いました．共有ドライブ（Shared Drive）を使っている場合は，オプションの指定方法を変えるなどちょっとした対応が必要です．

CI ツールは GitHub Actions を使いました．定期トリガーは on.schedule で設定できます． Head 情報はファイルに書いて actions/cache@v2 でキャッシュしました．

最後に Slack に通知して完了です．

まとめ

Sketch ファイルからアセットを自動で書き出す CI を組みました
先行事例を参考にしつつ，Git 中心ではなく Abstract を中心とした構成にしました
Abstract API を使って差分があるかどうかを検知したり，最新の Sketch ファイルを取得したりできました

One More Thing

静的解析の可能性について，本文中では Sketch Assistants について少しだけ言及しました． Assistants は Sketch アプリの中で動く拡張機能で，こちらも Node.js と TypeScript で開発できます．

試しに文言のバリデーションルールを書いてみたところ，不可視のレイヤーに古い文言が残っているなど，目視では発見しにくいミスを見つけることができました． Sketch を使ったワークフローにおいて，早い段階でミスを検知するための有力な選択肢になりそうです．

もしかすると Goodpatch Advent Calendar 2020 で誰かが何か書いてくれるかもしれません．

:bulb: 追記：Advent Calendar 15日目で @mnkd が Assistants について書いてくれました．日本語で丁寧に説明された文章は貴重だと思いますので，気になった方々はチェックしてみてください．

Sketch Assistants で DesignOps をアシスト - Qiita

References

Attribute を使って Unity から Cloud Firestore の読み書きを簡単にする

Sun, 13 Sep 2020 00:00:00 +0900

Unity で簡単な PvP ゲームを作りたいとき，Firebase の Cloud Firestore を使えばバックエンドのコーディングをしなくても動かしてみることができる． Firestore への読み書きはドキュメントに書かれた方法でも OK だが，Attribute を使うともっと簡単にできる．

概要

Cloud Firestore への読み書きを Attribute と独自クラスを使って簡単にする．

SDK で定義された FirestoreData や FirestoreProperty を使う
DocumentSnapshot から独自クラスに変換できるようにして，読み込みを簡単にする
独自クラスからディクショナリ型に変換できるようにして，書き込みを簡単にする

環境

Unity 2020.1.3f1
Cloud Firestore for Firebase 6.13.0

Attribute を使った読み込み（基礎編）

Cloud Firestore 読み書きの初歩的なドキュメントでは，取得した DocumentSnapshot を ToDictionary() でディクショナリ型に変換して値を読み書きする方法が紹介されている．ドキュメントの目的が Getting Started だと考えればこれはこれで正しい方法なのだが，次第にコードが増えていくと object のキャストも増えていくのが気になってくる．

実は Firestore SDK には FirestoreData や FirestoreProperty という Attribute がある．これらを使いつつ独自クラスを定義してあげると，DocumentSnapshot 型から独自クラスへの変換が ConvertTo<T>() メソッドを呼び出すだけで可能になる．

例えば Room を表すクラスを以下のように定義する．

[FirestoreData]
public class RoomEntity {
    [FirestoreProperty]
    public List<string> PlayerIds { get; set; }

    [FirestoreProperty]
    public int PlayerCount { get; set; }
}

この RoomEntity を使うと DocumentSnapshot から ConvertTo<RoomEntity>() で RoomEntity にキャストされたオブジェクトを得ることができる．

var db = FirebaseFirestore.DefaultInstance;

var roomDocument = await db.Collection("rooms").Document("room1").GetSnapshotAsync();

var roomEntity = roomDocument.ConvertTo<RoomEntity>();

独自クラスの定義さえ間違えていなければ良いので，都度 object をキャストするよりも簡単で安全と言える．

Attribute を使った読み込み（応用編）

場合によっては，もう少し凝ったクラスを定義したいこともある．

命名規則が違う場合

Firestore のフィールド名と C# コードのプロパティ名の命名規則が違う場合でも， FirestoreProperty の Name プロパティで紐づければ変換できるようになる．

例えば RoomEntity に対応する Room ドキュメントが Snake Case で定義されている場合．

{
    "player_ids": ["player1", "player2", "player3"],
    "player_count": 3
}

以下のように FirestoreProperty の Name を指定すればよい．

[FirestoreData]
public class RoomEntity {
    [FirestoreProperty(Name = "player_ids")]
    public List<string> PlayerIds { get; set; }

    [FirestoreProperty(Name = "player_count")]
    public int PlayerCount { get; set; }
}

プロパティを Readonly にしたい場合

独自クラスによっては，プロパティの書き込みを制限したい場合がある．例えば RoomEntity でいうと，PlayerCount は PlayerIds の要素数と整合性をとりたいので，Readonly にしたい．

結果から示してしまうと，以下のように Setter を private や空実装にすればよい．

[FirestoreData]
public class RoomEntity {
    [FirestoreProperty(Name = "player_ids")]
    public List<string> PlayerIds { get; set; }

    [FirestoreProperty(Name = "player_count")]
    public int PlayerCount {
        get => PlayerIds.Count;
        private set {}
    }
}

これは FirestoreProperty の実装に依存すると思われるが，Setter を private にしても問題なく変換することができた．ただし，Setter は private や空実装でも残しておく必要がある． Setter を定義しない場合でもコンパイルや実行は可能だが，実行時に警告が出てしまう．

独自クラスを使った書き込み

Firestore に書き込む場合には Set や Add といったメソッドを使うが，これらはディクショナリ型の引数を取る．

Attribute を使った読み込みができるようになったが，その反対に独自クラスをディクショナリ型に変換する方法は SDK では（おそらく）提供されていないので，簡単な Extension を実装する．

public static class FirestoreExtension
{
    public static Dictionary<string, object> ToFirestoreDictionary<T>(this T entity)
    {
        return typeof(T).GetProperties()
            .Where(prop => Attribute.IsDefined(prop, typeof(FirestorePropertyAttribute)))
            .ToDictionary(
                prop =>
                {
                    var attr = prop.GetCustomAttribute<FirestorePropertyAttribute>();
                    return attr.Name ?? prop.Name;
                },
                prop => prop.GetValue(entity, null)
            );
    }
}

この Extension を使うと Room は以下のように更新できる．

var db = FirebaseFirestore.DefaultInstance;

var roomDocument = await db.Collection("rooms").Document("room1").GetSnapshotAsync();

var roomEntity = roomDocument.ConvertTo<RoomEntity>();
roomEntity.PlayerIds.Add("player4");

await roomDocument.Reference.UpdateAsync(entity.ToFirestoreDictionary());

なお，実際にはクライアントサイドからドキュメントを直接更新することは少ないかもしれない．特に複数人で共有するリソースの場合，権限判断を含めてサーバーサイドで書き込む方が普通だろう．

まとめ & 感想

Cloud Firestore への読み書きを簡単にする方法をまとめた．

SDK で定義された FirestoreData や FirestoreProperty を使うとドキュメントへの読み書きを簡単にすることができた．クラスの定義を少し工夫すると，フィールド名の差を吸収したり，プロパティを Readonly にして書き込みミスを減らすこともできた．

クライアントサイドから読み書きできるから，プロトタイピングとの相性が良さそう．本番実装の際に書き込みのロジックはサーバーサイドに移行するとしても，リアルタイム読み込みのロジックは残せるところが多いかも．

参考

Get data with Cloud Firestore | Firebase

UIView に elevation っぽさを付ける

Mon, 23 Dec 2019 00:00:00 +0900

この記事は Goodpatch Advent Calendar 2019 の23日目です．

iOS アプリの UI デザインで elevation について意識することは Android の場合と比較すると少ないと思います．ただし，Material Design 自体はプラットフォームを限定せずに適用可能な考え方であり，elevation は Material Components を使うかどうかを別としても UI をデザインするために有用です．ということで UIView で elevation を表現する方法について Material Components も参考にしながら実装してみました．

概要

UIView の CALayer に影を付けて elevation っぽい表現をする
Elevation の値に応じて影の radius や offset を設定する
影は ambient と key の2種類をつける

という方針で実装しました．

環境

Xcode 11.0
iOS Simulator 13.0

MDC の影を試す

Material Components for iOS の影がどのような挙動になっているのかデモを作って確認してみます．

UIView に影をつける

Material Components (MDC) を参考にしながら，UIView に影をつけていきます．

Radius を設定する

まずは UIView の layer に最も単純な形で影をつけてみます．とりあえず elevation の高さ分だけ shadowRadius をつけてみます．

class CardView: UIView {
    func setShadowElevation(_ elevation: CGFloat) {
        let cornerRadius: CGFloat = 4
        self.layer.cornerRadius = cornerRadius

        self.layer.shadowColor = UIColor.black.cgColor
        self.layer.shadowRadius = elevation
        self.layer.shadowOffset = .zero
        self.layer.shadowOpacity = 0.33
    }
}

UIView の方はカードの中心（よりやや下？）に点光源があるような影のつき方で，MDC のような強い elevation は感じられません．

Offset を変更する

続いて shadowOffset も設定してみます．とりあえず elevation の高さ分だけ Y 軸方向にずらします．

self.layer.shadowOffset = CGSize(width: 0, height: elevation)

だいぶそれらしくなりました．ぱっと見はどちらも区別がつかないかもしれません．ただし，よく見てみると，なんとなく MDC の方が「カード」らしい存在感があるようにも見えます．特に elevation が小さいときが顕著です．

そこで elevation = 1 の両者を拡大して並べてみると，MDC の方は edge 付近の影が濃くなっていることが分かります．

Top	Bottom

MDC（左半分）の方が影の領域が広い．	MDC（左半分）は edge 付近の影がより濃い．薄くなっていく勾配も線形ではない．

2つの影をつける

Material Design Guideline の Light and shadows を読むと，Material Design では ambient と key の2種類の影が必要なことが分かります．

その実装である MDCShadowLayer.m を読むと，ガイドラインどおり ambient と key の2種類の影が設定されていることが分かります． Ambient は elevation によって offset が変わらない影で，opacity もかなり薄くつけられています．また Radius の値は elevation の一次関数で決まっていますが，ambient と key でそれぞれに係数が調整されています．

Ambient Opacity	Key Opacity
0.08	0.26

Elevation	Ambient Radius	Key Radius	Key Offset
0	-.–	-.–	-.–
1	0.88	0.66	1.19
2	1.77	1.33	2.42
3	2.66	1.99	3.65
5	4.44	3.33	6.11
8	7.11	5.33	9.81
13	11.56	8.66	15.96

というわけで，ambient 用の CALayer を subLayer として追加します．

class CardView: UIView {
    private weak var ambientShadowLayer: CALayer?

    let maxElevation: CGFloat = 16

    func setShadowElevation(_ elevation: CGFloat) {
        let cornerRadius: CGFloat = 4
        self.layer.cornerRadius = cornerRadius

        self.layer.shadowColor = UIColor.black.cgColor
        self.layer.shadowRadius = elevation
        self.layer.shadowOffset = CGSize(width: 0, height: elevation)
        self.layer.shadowOpacity = 0.33

        let ambientShadowLayer = self.ambientShadowLayer ?? { (view: UIView) -> CALayer in
            let superLayer = view.layer

            let layer = CAShapeLayer()
            layer.bounds = superLayer.bounds
            layer.anchorPoint = .zero

            let path = UIBezierPath(roundedRect: superLayer.bounds, cornerRadius: superLayer.cornerRadius)
            layer.path = path.cgPath
            layer.fillColor = view.backgroundColor?.cgColor

            let maskPath = UIBezierPath(rect: superLayer.bounds.insetBy(dx: -maxElevation * 2, dy: -maxElevation * 4))
            maskPath.append(path)

            let mask = CAShapeLayer()
            mask.path = maskPath.cgPath
            mask.bounds = superLayer.bounds
            mask.anchorPoint = .zero
            mask.fillRule = .evenOdd
            mask.fillColor = view.backgroundColor?.cgColor
            layer.mask = mask

            view.layer.addSublayer(layer)
            return layer
        }(self)
        self.ambientShadowLayer = ambientShadowLayer

        ambientShadowLayer.shadowColor = UIColor.black.cgColor
        ambientShadowLayer.shadowRadius = elevation
        ambientShadowLayer.shadowOffset = .zero
        ambientShadowLayer.shadowOpacity = 0.11
    }
}

レイヤーに設定した影が描画されるためにはレイヤーに塗りが必要ですが，レイヤーに塗りがあると元の UIView の描画を邪魔してしまうので mask を作って元の UIView 部分をくり抜いて透明化しています．

かなりそれらしくなりました．あとは opacity や offset の係数を調整して各々のいい感じに調整していけば良さそうです．

One More Thing

Ambient と key の2つの影を設定できるようになったので，それぞれに black 以外の色を指定することもできます．試しに orange を設定してみると次のようになりました．

アプリの性格やコンテンツの内容に合わせて色付きの影（ただし，もっとさりげない色で）を入れてみるのも良さそうです．

まとめ・感想

UIView で Material Design のような elevation の表現を実装する方法をまとめました．

Elevation によって影の radius と offset を設定した
Ambient と key の2つの影を設定した
- Ambient は元の UIView のサブレイヤーとして追加した
- そのままだと UIView の描画を邪魔するのでマスクをかけた

コスパを重視するなら key シャドーだけでも良さそうですが，ambient が加わるだけでカードの存在感が増したり，表現の幅が広がったりして面白いです．

参考

UILabel の改行をいい感じにする実験

Mon, 16 Dec 2019 00:00:00 +0900

この記事は Goodpatch Advent Calendar 2019 の16日目です．

API から動的にテキストを取得する場合，改行の位置を制御することはむずかしいです． UILabel には Word Wrap の機能がありますが，日本語では使えません．そこで，なんとか自力で改行格好悪い問題に対処できないか，実験をしてみました．

概要

iOS SDK の自然言語処理で単語の区切りを取得する
UILabel の改行位置を取得する
テキストの改行が単語の途中で挟まらないように自分で改行を挟んでから流し込む

という方針で試していきます．実験に使ったソースコードは GitHub にあります．

thedoritos/NaturalLabel: Experiment to break line naturally in UILabel

環境

iOS Simulator iOS 13

通常のレイアウト

まず，お題となるアプリを用意するために，通常どおり UILabel を使って標準的なレイアウトをしてみます．

Google Books API を使って適当な書籍の情報を取得して TableView に表示しました．

iPhone 11 Pro		iPhone 11 Pro Max

意外とそんなに気にならない結果になったような気もします．

完！！！

…では実験にならないので，もう少しいい感じにできる余地があるか試していきます．今回は次の3タイトルをベンチマークとして調整していきます．

やはり俺の青春ラブコメはまちがっている。14
隠れオタな彼女と、史上最高のラブコメをさがしませんか？
裏方キャラの青木くんがラブコメを制すまで。

遊びなので妥当性は気にしません．目についたものを選んだだけで他意はありません．

Natural Language

iOS には端末で自然言語処理を行える Natural Language Framework があります．これを使って日本語の改行を「いい感じ」にすることができないか試してみます．

Tokenizing Natural Language Text

まずは文庫本のタイトルを単語単位に分割してみます．ドキュメントの Tokenizing Natural Language Text に従って次のようにしました．

import UIKit
import NaturalLanguage

class NaturalLabel: UILabel {
    func naturalize() {
        guard let text = self.text else { return }
        debugPrint(text)

        let tokenizer = NLTokenizer(unit: .word)
        tokenizer.string = text

        let tokens = tokenizer.tokens(for: text.startIndex..<text.endIndex)
        let words = tokens.map({ text[$0] })
        debugPrint(words)
    }
}

3タイトルはそれぞれ次のように分割できました．

"やはり俺の青春ラブコメはまちがっている。14"
["やはり", "俺", "の", "青春", "ラブコメ", "は", "まちがっ", "て", "いる", "14"]

"隠れオタな彼女と、史上最高のラブコメをさがしませんか？"
["隠れ", "オタ", "な", "彼女", "と", "史上", "最高", "の", "ラブコメ", "を", "さがし", "ませ", "ん", "か"]

"裏方キャラの青木くんがラブコメを制すまで。"
["裏方", "キャラ", "の", "青木", "くん", "が", "ラブコメ", "を", "制", "す", "まで"]

単語の途中で改行がはさまらないようにできれば，「まち\nがっている」「史上最\n高」「ラブコ\nメ」といった不自然な改行は改善できそうです．一方で，「まちがっ\nている」「史上\n最高の」「制\nすまで」といった，間違いとは言えないが少し気持ち悪いかな（個人の感想です）という改行を防ぐことはできなさそうです．

Identifying Parts of Speech

もう少し手がかりを得るために，各単語（品詞）の種類を取得してみます．再びドキュメントの Identifying Parts of Speech を参考にして次のようにしました．

class NaturalLabel: UILabel {
    func naturalize() {
        guard let text = self.text else { return }
        debugPrint(text)

        let tagger = NLTagger(tagSchemes: [.lexicalClass])
        tagger.string = text
        let options: NLTagger.Options = [.omitPunctuation, .omitWhitespace]

        let tags = tagger.tags(in: text.startIndex..<text.endIndex, unit: .word, scheme: .lexicalClass, options: options)
        let words: [(String, String)] = tags.map({ (tag, range) in
            guard let tag = tag else { return (String(text[range]), "Unknown") }
            return (String(text[range]), tag.rawValue)
        })
        debugPrint(words)
    }
}

3タイトルはそれぞれ次のようにタグ付けされました．

"やはり俺の青春ラブコメはまちがっている。14"
[("やはり", "OtherWord"), ("俺", "OtherWord"), ("の", "OtherWord"), ("青春", "OtherWord"), ("ラブコメ", "OtherWord"), ("は", "OtherWord"), ("まちがっ", "OtherWord"), ("て", "OtherWord"), ("いる", "OtherWord"), ("14", "OtherWord")]

"隠れオタな彼女と、史上最高のラブコメをさがしませんか？"
[("隠れ", "OtherWord"), ("オタ", "OtherWord"), ("な", "OtherWord"), ("彼女", "OtherWord"), ("と", "OtherWord"), ("史上", "OtherWord"), ("最高", "OtherWord"), ("の", "OtherWord"), ("ラブコメ", "OtherWord"), ("を", "OtherWord"), ("さがし", "OtherWord"), ("ませ", "OtherWord"), ("ん", "OtherWord"), ("か", "OtherWord")]

"裏方キャラの青木くんがラブコメを制すまで。"
[("裏方", "OtherWord"), ("キャラ", "OtherWord"), ("の", "OtherWord"), ("青木", "OtherWord"), ("くん", "OtherWord"), ("が", "OtherWord"), ("ラブコメ", "OtherWord"), ("を", "OtherWord"), ("制", "OtherWord"), ("す", "OtherWord"), ("まで", "OtherWord")]

全て OtherWord という手がかりゼロの結果になりました．ちなみに英語だと NLTag の種類どおりにタグ付けされるのですが，日本語だと文字通り何の成果も得られませんでした．

ということで，気を取り直して単語の切れ目だけを手がかりとして進めます．

通常の改行位置を取得する

まずは通常の UILabel に流し込んだ String がどの位置で改行されるのかを取得します． iOS にはテキストをローレベルで触れる Core Text Framework があるので，ドキュメントを読みながら各行を取得するメソッドを書きました．

class NaturalLabel: UILabel {
    private func getLines(from text: String) -> [String] {
        guard let font = self.font else { return [] }

        let attributedString = NSMutableAttributedString(string: text)
        attributedString.addAttribute(.font, value: font, range: NSRange(location: 0, length: attributedString.length))

        let frameSetter = CTFramesetterCreateWithAttributedString(attributedString)

        let framePath = CGPath(rect: CGRect(x: 0, y: 0, width: self.frame.width, height: CGFloat.greatestFiniteMagnitude), transform: nil)
        let frame = CTFramesetterCreateFrame(frameSetter, CFRange(), framePath, nil)

        guard let lines = CTFrameGetLines(frame) as? [CTLine] else { return [] }
        return lines.map({ line in
            let cfRange = CTLineGetStringRange(line)
            let nsRange = NSRange(location: cfRange.location, length: cfRange.length)
            return NSString(string: text).substring(with: nsRange)
        })
    }
}

最終的には CTLine の Array が欲しい > CTFrameGetLines を呼び出したい > CTFrame が欲しい > CTFramesetterCreateFrame を呼び出したい > … という感じでドキュメントを辿っていけば良いです．

いい感じの改行をする

ようやく準備が整ったので，改行のロジックを考えて実装します．今回は遊びということでパッと思いついたもので実装していきます．

文字列を tokenize する
文字列を UILabel に流し込んで改行位置を取得する
Token を先頭から順に改行位置との衝突が起こるまで読んでいく（例：「ラブ\nコメ」で衝突）
衝突が起こる直前までの文字列を確定させて，確定行の String 配列に積む
衝突が起こる直前までの token を消費して，判定対象の token から除く
残りの文字列を UILabel に流し込んで改行位置を取得する
3-6 を token がなくなるまで繰り返す
残った文字列を確定行配列に積む
確定行配列を改行 \n で join する

日本語にすると難しいですが，コードだったらまだ分かりやすいかもしれません．実験用なので，衝突判定を String#contains で雑にやっていたり，文字列が長いときのパフォーマンスなどは考慮していません．

class NaturalLabel: UILabel {
    func naturalize() {
        guard let text = self.text?.replacingOccurrences(of: "\n", with: "") else { return }

        let tokenizer = NLTokenizer(unit: .word)
        tokenizer.string = text

        let tokens = tokenizer.tokens(for: text.startIndex..<text.endIndex)
        let words = tokens.map({ String(text[$0]) })
        guard words.count > 1 else { return }

        var fixedLines = [String]()
        var fixedTokens = 0

        while fixedTokens < tokens.count {
            let remainingTokens = tokens.dropFirst(fixedTokens)
            let remainingText = String(text[remainingTokens.first!.lowerBound...])
            let remainingLines = self.getLines(from: remainingText)

            guard let brokenToken = remainingTokens.first(where: {
                let word = text[$0]
                return !remainingLines.contains(where: { $0.contains(word) })
            }) else {
                fixedLines += [remainingText]
                fixedTokens += remainingTokens.count
                continue
            }

            fixedLines += [String(text[remainingTokens.first!.lowerBound..<brokenToken.lowerBound])]
            fixedTokens = remainingTokens.firstIndex(of: brokenToken)!
        }

        self.text = fixedLines.joined(separator: "\n")
    }
}

アプリを実行してみた結果は次のようになりました．

iPhone 11 Pro		iPhone 11 Pro Max

Before	After	Size
やはり俺の青春ラブコメはまちがっている。14	やはり俺の青春ラブコメはまちがっている。14	11 Pro Max
隠れオタな彼女と、史上最高のラブコメをさがしませんか？	隠れオタな彼女と、史上最高のラブコメをさがしませんか？	11 Pro
裏方キャラの青木くんがラブコメを制すまで。	裏方キャラの青木くんがラブコメを制すまで。	11 Pro Max

思ってたよりも良くなっているような気がします（個人の感想です）．

まとめ・感想

日本語のテキストの改行問題に対して自然言語処理で解決できそうか実験してみました．

iOS の Natural Language Framework を使ってテキストを単語単位に分割した
Core Text Framework を使って UILabel の改行位置を取得した
単語の中で改行が行われないように \n を挟んでみた
思ってたより良くなった（個人の感想です）

想像していたとおり，「史上\n最高」などは防げませんでしたが，改行問題をある程度解決することができました．ただし，実用に足りるかというと微妙かもしれません．

Apple の API で品詞の種類が取得ができなかったときは少しあせりましたが，なんにせよ Apple が「ラブコメ」を1単語として認識してくれていたのは良かったです．これがなかったら完全に詰んでいました．

2019年，完結おめでとうございます．アニメ3期もよろしくお願いします．

参考

UI デザイナーのための iOS レイアウト入門

Mon, 09 Dec 2019 00:00:00 +0900

この記事は Goodpatch Advent Calendar 2019 の9日目です．

iOS レイアウトの仕組みを知らずに iOS の UI デザインをすることはできません．つまり UI デザイナーは，iOS の提供する UI コンポーネントや Auto Layout について基本的な仕組みは理解しておく必要があります．

その助けになるといいなと思ってこの記事を書きました．

概要

この記事では次の内容について書きます．

Auto Layout のドキュメントを紹介する
超基本的な UIKit コンポーネントを紹介する

iOS レイアウトの基礎に限ったとしても，この記事だけで内容を網羅することは到底できません．この記事では，iOS レイアウトを学び始めるための入り口やキーワードを提供することを目的とします．

補足: SwiftUI

2019 年の WWDC で新しい UI システムの SwiftUI が発表されましたが，この記事は従来の UIKit の使用を想定して書いています．もし，これから新しく iOS アプリを作るために実装まで本格的に学びたいのであれば SwiftUI を学ぶと良いです．ただし，UIKit について知っていることは無駄にならないし，ここ 1-2 年では新規/継続開発を問わず UIKit はまだ使われ続けると予想します．

Auto Layout 公式ドキュメント

Auto Layout については Apple Developer のページに必要十分なドキュメントがあります．

Auto Layout Guide: Understanding Auto Layout

Getting Started と Auto Layout Cookbook のセクションについては目を通しておくと良いです．英語に苦手意識がある場合は，ざっと眺めて雰囲気だけ掴んでおき，以下で紹介する日本語の記事などを読んで基礎知識をつけてから戻ってくると良いです．ただし，最終的には公式ドキュメントは必ず読むことになると思います．

入門ドキュメント

Zaim のブログに akatsuki174 さんが投稿した記事が分かりやすくまとまっています．

公式ドキュメントを網羅する内容ではないので，公式ドキュメントは別途読むようにします．一方で，公式ドキュメントに載っていない図解や練習問題もあるので，併せて読んでみると良いと思います．

UIKit コンポーネント

Auto Layout について基本的な仕組みが分かったら，UIKit のコンポーネントについて理解していきます．

まず，前提として HIG を読んでいて基本的なコンポーネントについては知っているものとします．

Themes - iOS - Human Interface Guidelines - Apple Developer

その上で，一般的なアプリを実装するために，まずは次のコンポーネントについてより深く知っておくと良いです．以下のリンクは Developer 向けの内容なので詳細まで読み込む必要はないですが，UI を実装するために Developer がどういう手段を持っているのか触りだけでも知っておくと UI デザインをするときに考慮すべきポイントが分かるようになると思います．

各コンポーネントには設定できる attributes（属性）があり，主要なものは Interface Builder Attributes の項に記述されているので必ず読むようにします．少なくともこれら attributes の観点を考慮できているだけで，かなり実装しやすいデザインになります．

UILabel

UILabel はテキストを表示するための基本コンポーネントです．次の画像は Xcode の Attributes Inspector で見ることができる UILabel の attributes です．

詳しい説明は前述の Interface Builder attributes の項で確認するとして，個人的な意見を補足すると次のとおりです．

Font: System フォントを使うのが，文字の読みやすさという点でもアプリの容量の点でも有利になる．

Lines: 最大2行まで表示して末尾は Truncate という場合や，最後の行まで全て表示する（Lines = 0）という場合に指定する．なお，この attribute を見ると UILabel は「最大文字数」を指定する設計ではないということが分かる．

経験上 UILabel のサイズは可変にすることが多く，width や height 制約を直接的には指定しないことが多い．その理由としては，テキストというコンテンツが内容や多言語化（i18n）によって大きく分量が変わるため．また，UIImageView のようにサイズやアスペクト比を指定しないとコンテンツが pixelate してしまうといった強い制約がないため．

Autoshrink: 最終手段としてのみ使い，乱用すべきではない．文字の大きさは意味的に重要なため．文字数が収まらないときはレイアウトを工夫するか truncate で対応する．

UILabel は最も頻出するコンポーネントなので，他の attributes についてもしっかり確認しておくことをおすすめします．

UIImageView

UIImageView は画像を表示するための基本コンポーネントです．

同様に個人的な意見を補足すると次のとおりです．

Content Mode: ドキュメントの Understanding How Images Are Scaled の項にも記述がある，最重要 attribute．指定できる値についてはドキュメントに詳しく説明があるが，通常はアスペクト比を保つことができる AspectFit (scaleAspectFit) か Aspect Fill (scaleAspectFill) を使う．

なお，Aspect Fill は画像の中心がくり抜かれるので「画像の上端 & 左右両端を合わせて，下端は裁ち落とし」というレイアウトはひと工夫必要だということが分かる．また，iOS の ImageView にはコンテンツサイズに合わせて動的に大きさを変える attribute がないことも分かる．他のプラットフォームでは Android の wrap_content や Unity UI の Preferred Size など指定ができることが多いので，少し意外な設計だと思っている．

UIImageView も頻出するコンポーネントであり，かつ前述のように制約が強くレイアウトの基準になりやすいコンポーネントなので，レイアウトの仕組みについて必ず知っておくべきです．

UIButton

UIButton はその名のとおり，ボタンを表示するための基本コンポーネントです．

State Config: UIButton は Default，Highlighted，Selected，Disabled の状態に対して別々に attributes を設定できるようになっている．裏を返すとこれらの状態については UI デザインで考慮しておくべき．ただし，Selected 状態を使わない場合も多いので，必要最低限としてはその他3状態を考慮しておくと良い． Type 属性にデフォルト値である System を指定すると，Default 状態を設定するだけで他の状態には Tint カラーを使って対応してくれるので，第1の選択肢として検討する．

Image: Title の隣に表示する画像を指定できる．ただし，レイアウトの自由度が低く，標準の UIButton の提供する仕組みでは UI デザインを再現できない場合も多い．

UIButton はシンプルですが少しクセのあるコンポーネントです． Sketch ファイルのような静的な UI デザイン成果物上では各種状態が考慮できていなかったり，なんとなくで置かれている（ように見える）アイコンを実装するために独自カスタマイズが必要になったりということがあります． UIButton の仕様を知っているとこういった考慮漏れや「なんとなく」が少なくなると思います．

UIStackView

UIStackView はコンポーネントを並べるためのコンポーネントです．

Distribution: 指定できる値について詳しくはドキュメントに説明があるが，Fill 系と Spacing 系の2種類がある．基本的にはコンポーネントを縦（or 横）に等間隔で並べるために Spacing 系を，等しい高さ（幅）で敷き詰めるために Fill 系を使う．

UIStackView を用いてコンポーネントを縦横に整列するレイアウトは，iOS UI デザインにおいて頻出するパターンです． UIStackView の仕組みを知っていれば，iOS アプリの UI を見たときに View の構造を推測しやすくなると思います．

Next Action

まだ紹介していないコンポーネントについても，Developer Documentation を読んで見ると良いかもしれません．特に UITextField，UISegmentedControl, UITableViewCell あたりは頻出なのでおすすめです．

また，macOS を使っているなら誰でも AppStore から Xcode をインストールできるので，実際に Auto Layout がどんなものか触ってみてください． YouTube をはじめとして，動画で解説してくれているリソースもたくさんあります．あるいは友達や同僚に iOS Developer がいるなら，Xcode を開いて質問にいけばきっと喜んで教えてくれると思います．

まとめ・感想

この記事では次の内容について書きました．

Auto Layout のドキュメントを紹介した
- 公式ドキュメント
- Zaim のブログ記事
超基本的な4つの UIKit コンポーネントを紹介した
- UILabel (ドキュメント)
- UIImageView (ドキュメント)
- UIButton (ドキュメント)
- UIStackView (ドキュメント)

iOS のレイアウトを学び始めるためのとっかかりを得られたと感じてもらえれば嬉しいです．