NSAffineTransform — ce este, tipuri de transformări și cum se aplică

Ce este NSAffineTransform?

NSAffineTransform — este o clasă din framework-ul AppKit, disponibilă doar pe macOS. Reprezintă o transformare afină în spațiul bidimensional printr-o matrice 3×3. Spre deosebire de CGAffineTransform din Core Graphics (care este disponibil pe iOS), NSAffineTransform este un înveliș orientat pe obiecte al structurii CGAffineTransform, adăugând metode convenabile pentru lucrul cu NSBezierPath, NSPoint și NSSize.

Transformarea afină — este o transformare a planului care păstrează relația „punctul se află pe o dreaptă” și paralelismul dreptelor. Cu alte cuvinte, după o transformare afină, liniile paralele rămân paralele, iar dreptele — drepte. Cu toate acestea, distanțele, unghiurile și ariile se pot modifica: scalarea, rotirea și înclinarea sunt cazuri particulare ale transformărilor afine.

Pe iOS, echivalentul NSAffineTransform este structura CGAffineTransform din Core Graphics. Ambele API-uri se bazează pe același model matematic — matricea de transformare afină 3×3, unde ultimul rând este întotdeauna [0, 0, 1]. Diferența constă în faptul că NSAffineTransform este o clasă (cu retain/release în Objective-C), iar CGAffineTransform este o structură (tip de valoare) în Swift și C.

Tipuri de transformări afine

NSAffineTransform suportă patru tipuri de bază de transformări: translate (translație), scale (scalare), rotate (rotire) și shear (înclinare). Fiecare tip este reprezentat printr-o metodă separată și poate fi aplicat atât unui obiect de transformare existent, cât și utilizat pentru a crea unul nou.

Translate — translație

Translate adaugă o deplasare la coordonatele tuturor punctelor obiectului. Parametrii deltaX și deltaY specifică magnitudinea deplasării pe orizontală și respectiv pe verticală. O valoare pozitivă deltaX deplasează la dreapta, deltaY — în sus. Translate nu modifică forma sau dimensiunea obiectului — doar poziția acestuia.

Scale — scalare

Scale multiplică coordonatele punctelor cu un factor dat. La scalarea uniformă (un singur parametru), obiectul se mărește sau se micșorează proporțional. La scalarea neuniformă, forma se denaturează. Factorul 1.0 lasă dimensiunea neschimbată, mai mare de 1.0 — mărește, de la 0.0 la 1.0 — micșorează. Valorile negative creează oglindire.

Rotate — rotire

Rotate rotește obiectul în jurul originii coordonatelor cu un unghi dat. Unghiul de rotație pozitiv corespunde rotației în sens invers acelor de ceas. rotateByDegrees acceptă grade (0–360), rotateByRadians — radiani (0–2π). Rotirea se efectuează întotdeauna față de punctul (0, 0), prin urmare pentru rotirea în jurul unui punct arbitrar, rotate trebuie combinat cu translate.

Reprezentarea matriceală 3×3

Transformarea afină în NSAffineTransform este reprezentată de o matrice 3×3, unde ultimul rând este întotdeauna [0, 0, 1]. Aceasta este o reprezentare matematică standard care permite prezentarea combinației de transformări ca produs de matrice. Structura matricei este definită prin NSAffineTransformStruct, care conține șase componente semnificative: m11, m12, m21, m22, tX, tY.

Componentele m11, m12, m21, m22 sunt responsabile pentru scalare, rotire și înclinare. Componentele tX și tY — pentru translație. În configurația standard (matricea unitate) m11 = 1, m22 = 1, celelalte sunt 0. Pentru obținerea valorilor curente ale matricei se utilizează transformStruct — proprietatea NSAffineTransform care returnează structura NSAffineTransformStruct.

Înmulțirea matricelor este o operație necomutativă. Aceasta înseamnă că ordinea aplicării transformărilor contează: translate + rotate dă un rezultat diferit de rotate + translate. La combinare, NSAffineTransform înmulțește noua matrice la stânga cu matricea curentă: newMatrix = operation × currentMatrix. Prin urmare, ultima transformare adăugată se aplică prima.

Combinarea transformărilor

NSAffineTransform permite combinarea mai multor transformări într-un singur obiect. Fiecare apel translateXBy:yBy:, scaleBy: sau rotateByDegrees: modifică matricea internă — înmulțește matricea curentă cu matricea transformării corespunzătoare. Aceasta permite crearea unei transformări complexe dintr-o secvență de operații simple.

Pentru inversarea transformării combinate se utilizează metoda invert. Inversa creează o nouă transformare afină care anulează transformarea originală: dacă aplicăm unui punct transformarea originală, apoi pe cea inversată, punctul revine la poziția inițială. Inversa este utilă pentru anularea transformării contextului înainte de desenarea elementelor UI care nu trebuie să fie transformate.

Verificarea dacă transformarea este identitate (nu modifică coordonatele) se poate face prin proprietatea isIdentity. Transformarea de identitate este matricea unitate, la înmulțirea cu care coordonatele punctului nu se modifică. Un nou obiect NSAffineTransform este creat ca transformare de identitate. Această proprietate este utilă pentru optimizare: dacă transformarea este de identitate, aplicarea ei poate fi omisă.

Aplicarea la obiecte și context

NSAffineTransform poate fi aplicat la patru tipuri de obiecte: NSPoint, NSSize, NSBezierPath și contextul grafic NSGraphicsContext. Pentru fiecare scop există o metodă separată: transformPoint:, transformSize:, transformBezierPath: și set.

Transformarea punctelor și dimensiunilor

Metoda transformPoint: înmulțește matricea de transformare cu vectorul de coordonate al punctului (x, y, 1), returnând noua poziție a punctului. transformSize: funcționează similar, dar nu ia în considerare componentele tX și tY — translația nu se aplică, doar scalarea, rotirea și înclinarea. Acest lucru este util pentru transformarea vectorilor și dimensiunilor care nu trebuie să fie deplasate.

Transformarea traseelor NSBezierPath

Metoda transformBezierPath: creează un nou obiect NSBezierPath, fiecare punct al căruia este transformat conform matricei NSAffineTransform. Traseul original nu se modifică — se creează o copie cu coordonate transformate. Aceasta este o operație costisitoare pentru trasee complexe cu un număr mare de noduri.

Aplicarea la contextul grafic

Metoda set aplică transformarea la contextul grafic curent (NSGraphicsContext), modificând CTM-ul (Current Transformation Matrix). După apelarea set, toate desenările ulterioare în acest context vor fi transformate. Pentru transformarea temporară, utilizați saveGraphicsState / restoreGraphicsState înainte și după set.

Exemple de cod în Swift

Să examinăm exemple practice de utilizare a NSAffineTransform într-o aplicație macOS pentru transformarea obiectelor grafice.

Crearea și combinarea transformărilor

Exemplul creează un NSAffineTransform care combină translația, rotirea și scalarea. Mai întâi obiectul este deplasat cu (100, 50), apoi rotit cu 45 de grade și, în final, mărit de 1.5 ori. Ordinea contează: rotate după translate produce rotirea față de noua origine a coordonatelor.

import AppKit

let transform = NSAffineTransform()
transform.translateXBy(100, yBy: 50)
transform.rotateByDegrees(45)
transform.scaleBy(1.5)

// Aplicare la punct
let point = NSPoint(x: 10, y: 20)
let transformedPoint = transform.transform(point)

// Aplicare la dimensiune
let size = NSSize(width: 100, height: 50)
let transformedSize = transform.transform(size)

Transformarea contextului pentru desenare

Exemplul arată aplicarea NSAffineTransform la contextul grafic prin set și concat. După aplicarea transformării, toate desenările ulterioare se efectuează în sistemul de coordonate transformat. Salvarea stării grafice prin saveGraphicsState permite revenirea la matricea originală.

func drawWithTransform(in rect: NSRect) {
    guard let ctx = NSGraphicsContext.current
    else { return }

    ctx.saveGraphicsState()

    let xfm = NSAffineTransform()
    xfm.translateXBy(rect.midX, yBy: rect.midY)
    xfm.rotateByDegrees(30)
    xfm.scaleBy(0.8)
    xfm.concat()

    // Desenare în sistemul de coordonate transformat
    let path = NSBezierPath(roundedRect: NSRect(
        x: -50, y: -50,
        width: 100, height: 100
    ), xRadius: 10, yRadius: 10)
    NSColor.blue.setFill()
    path.fill()

    ctx.restoreGraphicsState()
}

Transformarea traseului NSBezierPath

Exemplul demonstrează crearea unei copii a NSBezierPath cu coordonate transformate. Traseul original rămâne neschimbat, iar copia transformată poate fi desenată separat — acest lucru este util pentru crearea elementelor repetitive în diferite poziții.

func createTransformedTriangle() -> NSBezierPath {
    let triangle = NSBezierPath()
    triangle.move(to: NSPoint(x: 0, y: 0))
    triangle.line(to: NSPoint(x: 100, y: 0))
    triangle.line(to: NSPoint(x: 50, y: 100))
    triangle.close()

    let xfm = NSAffineTransform()
    xfm.translateXBy(200, yBy: 100)
    xfm.scaleXBy(1.5, yBy: 1.5)
    xfm.rotateByDegrees(45)

    let transformed = xfm.transform(triangle)
    return transformed
}