[sectionBegin," Using the Gyro ",0,"ZScript Primer (Press to expand this section)",
	[varDef,zbPrimerTempOpenGY][varDef,zbInitDocSavedGY,0][varDef,zbInitSavedDocGY,""]
	[iPress,7442]
	[if,(zbPrimerTempOpenGY),
		[iKeyPress,'N',[iPress,document:newdocument]]
	, // else
		[if,[messageYesNo,"OK to clear all customized tools, lights and materials?","DOCUMENT MUST BE CLEARED BEFORE PROCEEDING..."],
			[if,[isEnabled,document:save],
				[if,[messageYesno,"Would you like to save this document before proceeding?","Document has not been saved."],
					[iPress,document:saveas]
					[varSet,zbInitSavedDocGY,[fileNameGetLastUsed]]
					[varSet,zbInitDocSavedGY,1]
				] // end if (user saves)
			] // end if (save enabled)
			[Note,"One moment please...",,2]
			[iKeyPress,13,[iReset]]
			[varSet,zbPrimerTempOpenGY,1]
		, // else (user won't reset)
			[iUnPress,0][exit]
		] // end if (wanna reset?)
	] // end if PrimerTemp
	[Note,,transform:rotate,-1]
	[Note,,transform:scale,-1]
	[Note,"This primer describes the Canvas Gyro, a unique helper that appears when you enter a Transform mode (Move, Scale or Rotate).",transform:move,-1]
	[Note,"\n\n\C909090(Click to continue)\Cc0c0c0",,0]
] // end sectionBegin
[pd][paintBackSliver,2,40,40,40][pd]
Whenever you draw a 3D object,[penMove,-3]* you can immediately enter a Transform mode: [buttonFind,transform:move,Move], [buttonFind,transform:scale,Scale] or [buttonFind,transform:rotate,Rotate]. The Gyro, a unique helper that makes it easy to control transformations, appears [iButton,"show me","Draw an object and enter a Transform mode",
	[iPress,tool:cube3D]
	[iColorSet,150,150,255]
	[iSet,material:itemInfo,1]
	[iSet,texture:itemInfo,0]
	[canvasClick,440,240,440,242]
	[transformSet,320,240,0,120,120,120,-10,-10,0]
	[iPress,transform:move]
]. // end iButton

The Gyro looks like three interlocking rings of red, green and blue oriented along the object's axes, plus a fourth gray ring that is always lying flat against the canvas. Where the colored rings meet, their intersections are colored differently: cyan for the blue-green intersection, magenta for the red-blue intersection, and yellow for the red-green intersection.

Axes are imaginary reference lines that can be thought of as pins sticking through the center of the object. Looking at the Gyro, the X axis is like a pin sticking through the cyan-colored intersections, in a horizontal direction. The Y axis is sticking through the the magenta-colored intersections in a vertical direction, and the Z axis is sticking through the yellow intersections in a near-to-far direction.

Generally, you can use the Gyro to control how the object is moved, scaled or rotated by clicking and dragging inside the Gyro, outside the Gyro, on one of the rings, or on one of the intersections.

Here are some examples using basic shapes [iButton,"draw them","Draw some basic shapes on the canvas",
	[iUnpress,transform:editobject]
	[iPress,transform:drawpointer]
	[iPress,layer:modifiers:clear]

	[iPress,tool:sphere3D]
	[iColorSet,255,50,50]
	[iSet,material:itemInfo,1]
	[iSet,texture:itemInfo,0]
	[canvasClick,320,240,320,242]
	[transformSet,270,240,0,150,150,150,0,0,0]

	[iPress,tool:cube3D]
	[iColorSet,150,150,255]
	[iSet,material:itemInfo,1]
	[iSet,texture:itemInfo,0]
	[canvasClick,440,240,440,242]
	[transformSet,530,240,0,100,100,100,0,0,0]
	[iPress,transform:move]
]. // end iButton	

In each case, the blue cube is the object being transformed.

When in [buttonPress,transform:move,"Move mode"], clicking and dragging inside the Gyro simply moves the cube along the canvas. When moving along the canvas, it stays aligned to the canvas; when moving along another painted element, such as the red sphere, it stays aligned to that element [iButton,"show me","Move the cube",
	[iPress,transform:move]
	[canvasStroke,( )]
]. // end iButton
[pd]
Clicking and dragging outside the Gyro moves the cube toward you (mouse/tablet moving downward) or away from you toward the canvas (mouse/tablet moving upward) [iButton,"show me","Move by dragging outside the Gyro",
	[canvasStroke,(ZObjStrokeV01n15x3=H514V119P0H514V119P1H515V120P1H517V131P1H520V169P1H521V190P1H525V223P1H528V251P1H534V295P1H540V337P1H543V355P1H543V360P1H543V364P1H543V370P1H543V370P1)]
	[delay,.6]
	[canvasStroke,(ZObjStrokeV01n35x3=H513V393P0H513V393P1H513V392P1H514V389P1H514V386P1H514V382P1H516V372P1H518V363P1H522V345P1H524V333P1H526V325P1H527V315P1H528V304P1H528V296P1H529V285P1H529V270P1H530V260P1H530V237P1H532V210P1H533V195P1H534V186P1H535V173P1H535V171P1H535V169P1H534V168P1H534V167P1H531V130P1H531V127P1H532V124P1H532V123P1H532V122P1H532V121P1H533V117P1H533V116P1H533V116P1)]
]. // end iButton
[pd]
Clicking and dragging one of the rings moves the cube in the same plane that the ring lies in. For example, dragging the green ring moves the cube in the side-to-side/near-to-far direction, but not up and down [iButton,"show me","Drag the green ring",
	[canvasStroke,( )]
]. // end iButton
Dragging the gray ring always moves the cube parallel to the canvas, no matter which way it's rotated [iButton,"show me","Drag the gray ring",
	[canvasStroke,(ZObjStrokeV01n49x3=H315V196P0H315V196P1H314V196P1H313V191P1H312V188P1H311V185P1H309V180P1H305V173P1H301V168P1H298V166P1H293V162P1H287V158P1H273V152P1H264V150P1H250V149P1H231V148P1H221V148P1H214V148P1H212V149P1H209V151P1H201V157P1H196V161P1H182V173P1H171V182P1H169V185P1H166V192P1H165V200P1H165V208P1H165V216P1H167V227P1H171V236P1H177V243P1H184V248P1H193V253P1H226V267P1H245V271P1H262V273P1H278V275P1H298V274P1H310V270P1H323V264P1H336V255P1H349V242P1H363V216P1H370V204P1H371V197P1H371V193P1H371V192P1H371V192P1)]
]. // end iButton
[pd]
Clicking and dragging one of the intersections moves the cube along that particular axis only (as if you were sliding it along the length of the "pin" sticking through it). For example, dragging the magenta intersection moves the cube up and down, and not in any other direction [iButton,"show me","Drag the magenta crosshairs",
	[canvasClick,437,154]
	[canvasStroke,(ZObjStrokeV01n47x3=H443V156P0H443V156P1H443V155P1H443V153P1H443V148P1H444V136P1H445V126P1H444V117P1H444V102P1H444V90P1H443V80P1H443V76P1H443V77P1H442V84P1H440V96P1H440V112P1H440V136P1H440V152P1H440V166P1H440V184P1H441V200P1H441V234P1H440V246P1H438V261P1H437V271P1H436V280P1H435V287P1H435V293P1H435V299P1H435V304P1H435V309P1H435V312P1H435V311P1H435V309P1H437V304P1H439V294P1H440V258P1H440V242P1H440V228P1H440V217P1H440V207P1H439V198P1H438V185P1H436V170P1H435V160P1H435V156P1H435V156P1)]
]. // end iButton
[pd][pd]
When in [buttonPress,transform:scale,"Scale mode"], the Gyro controls scaling in similar ways. Clicking and dragging inside or outside the Gyro simply resizes the cube overall -- dragging toward the center shrinks it, and dragging away from the center enlarges it [iButton,"show me","Scale the cube",
	[transformSet,432,241,-93,100,100,100,-1.32,59.82,0]
	[iPress,transform:scale]
	[canvasStroke,(ZObjStrokeV01n49x3=H449V281P0H449V281P1H450V284P1H451V287P1H454V293P1H458V301P1H461V308P1H463V312P1H463V314P1H462V312P1H461V309P1H460V306P1H457V301P1H454V291P1H452V285P1H450V279P1H448V274P1H448V273P1H447V270P1H447V269P1H446V262P1H445V261P1H445V260P1H445V259P1H444V259P1H444V258P1H444V259P1H445V260P1H445V261P1H445V262P1H446V262P1H446V264P1H447V265P1H447V266P1H448V267P1H448V268P1H448V269P1H449V270P1H449V271P1H450V273P1H450V274P1H451V274P1H451V275P1H451V276P1H451V277P1H452V277P1H452V278P1H452V279P1H449V281P1)]
]. // end iButton
[pd]
Similar to Move mode, clicking and dragging one of the rings scales the cube in the same plane that the ring lies in. For example, dragging the green ring scales the cube's width and depth, but not its height [iButton,"show me","Drag the green ring",
	[canvasStroke,(ZObjStrokeV01n49x3=H352V242P0H352V242P1H351V242P1H351V243P1H348V244P1H338V247P1H328V248P1H311V252P1H293V261P1H278V268P1H251V276P1H214V282P1H177V289P1H174V289P1H178V289P1H194V287P1H221V282P1H252V275P1H303V263P1H334V255P1H362V247P1H379V241P1H390V237P1H398V234P1H400V234P1H400V233P1H403V232P1H404V232P1H403V232P1H402V232P1H400V233P1H398V234P1H396V234P1H393V235P1H390V236P1H388V236P1H385V237P1H383V238P1H376V239P1H374V240P1H372V240P1H367V242P1H364V242P1H360V243P1H358V244P1H357V244P1H356V244P1H354V245P1H352V242P1)]
]. // end iButton
Dragging the gray ring has no effect in Scale mode.

Again, clicking and dragging one of the intersections scales that cube only in the direction of that particular axis. For example, dragging the magenta intersection only scales the cube's height [iButton,"show me","Drag the magenta crosshairs",
	[canvasClick,437,154]
	[canvasStroke,( )]
]. // end iButton
[pd]
When in [buttonPress,transform:rotate,"Rotate mode"], clicking and dragging inside the Gyro rotates the cube freely [iButton,"show me","Rotate the cube",
	[iPress,transform:rotate]
	[transformSet,432,241,-93,100,100,100,-1.32,59.82,0]
	[canvasStroke,(ZObjStrokeV01n42x3=H432V198P0H432V198P1H431V197P1H421V191P1H406V187P1H384V185P1H359V184P1H341V187P1H327V192P1H317V198P1H306V209P1H294V224P1H283V257P1H283V279P1H286V301P1H298V326P1H313V344P1H353V369P1H381V379P1H416V381P1H453V372P1H480V359P1H501V340P1H524V317P1H545V273P1H538V248P1H522V226P1H501V208P1H484V197P1H477V193P1H472V192P1H467V191P1H458V191P1H453V192P1H449V193P1H445V195P1H443V196P1H441V198P1H441V199P1H439V200P1H438V201P1H432V198P1)]
]. // end ibutton
[pd]
Clicking and dragging outside the Gyro acts the same way as in Move mode -- it moves the cube toward you or away from you [iButton,"show me","Drag outside the Gyro",
	[canvasStroke,(ZObjStrokeV01n15x3=H514V119P0H514V119P1H515V120P1H517V131P1H520V169P1H521V190P1H525V223P1H528V251P1H534V295P1H540V337P1H543V355P1H543V360P1H543V364P1H543V370P1H543V370P1)]
	[delay,.6]
	[canvasStroke,(ZObjStrokeV01n35x3=H513V393P0H513V393P1H513V392P1H514V389P1H514V386P1H514V382P1H516V372P1H518V363P1H522V345P1H524V333P1H526V325P1H527V315P1H528V304P1H528V296P1H529V285P1H529V270P1H530V260P1H530V237P1H532V210P1H533V195P1H534V186P1H535V173P1H535V171P1H535V169P1H534V168P1H534V167P1H531V130P1H531V127P1H532V124P1H532V123P1H532V122P1H532V121P1H533V117P1H533V116P1H533V116P1)]
]. // end iButton
[pd]
Clicking and dragging one of the rings rotates the cube as if that ring were a steering wheel. For example, dragging the green ring rotates the cube around the Y-axis (as if a pin were stuck through the magenta intersections) [iButton,"show me","Drag the green ring",
	[canvasStroke,(ZObjStrokeV01n46x3=H454V245P0H454V245P1H452V245P1H443V246P1H433V246P1H423V246P1H389V243P1H365V241P1H344V240P1H312V240P1H290V240P1H279V240P1H271V240P1H260V240P1H259V240P1H260V240P1H275V242P1H295V243P1H317V244P1H326V244P1H340V245P1H350V245P1H358V245P1H370V245P1H377V245P1H388V246P1H404V246P1H419V246P1H442V246P1H452V245P1H461V245P1H469V244P1H470V243P1H471V243P1H472V243P1H471V243P1H470V243P1H469V243P1H466V243P1H465V243P1H463V243P1H461V243P1H460V244P1H457V244P1H456V244P1H454V245P1)]
]. // end iButton
Dragging the gray ring rotates the cube clockwise or counterclockwise on the canvas, no matter how it's oriented [iButton,"show me","Drag the gray ring",
	[canvasStroke,( )]
]. // end iButton
[pd]
Clicking and dragging one of the intersections has no effect in Rotate mode.

You can quickly switch between Transform modes by using keyboard shortcuts. The Move mode shortcut is [hotKeyText,transform:move], Scale mode is [hotKeyText,transform:scale], and Rotate mode is [hotKeyText,transform:rotate]. You can exit the Transform modes, and remove the Gyro, by selecting the ((Draw Pointer)) (keyboard shortcut [hotKeyText,transform:drawpointer]).

[iButton," Return to your original (saved) document ","Return to your original file",
	[fileNameSetNext,zbInitSavedDocGY]
	[if,[isEnabled,document:save],
		[iKeyPress,'N',[iPress,document:open]]
	, // else nothing to save
		[iPress,document:open]
	] // end if
	[varSet,zbInitSavedDocGY,""]
	[varSet,zbInitDocSavedGY,0]
	[varSet,zbPrimerTempOpenGY,0]
] // end iButton
[pd][pd]
[fontSetSizeSmall]*Although designed for 3D objects, the Gyro also works on 2D painting tools, when applied using the [penMove,0,-6][buttonFind,stroke:dragrect,"Drag-Rect stroke"][penMove,0,6]. In most cases, you cannot Rotate them, but you can Move and Scale them. Also, when in a Transform mode, you can freely change [penMove,0,-6][buttonFind,28601,Textures][penMove,0,6] and [penMove,0,-6][buttonFind,28701,Alphas][penMove,0,6] and see these changes made on the element being transformed.[fontSetSizeMedium]

[pd][paintBackSliver,2,40,40,40][pd][sectionEnd] // end of Using the Gyro

