Kangaroo2.3.

3Releasenotes
11/07/2017

KangarooisalibraryandsetofGrasshoppercomponentsforform-finding,physicssimulation,
andgeometricconstraintsolving.

ThesenotesareabriefoverviewandintroductiontothefeaturesofKangaroo.Formoredetails,
examplefiles,ortoaskanyquestions,pleasevisittheKangaroosectionoftheGHforum,andI
willdomybesttoanswer.

IfyouareusingtheRhinoWIP,GrasshopperandKangaroonowcomeincluded,soyoucanskip
theinstallationdescribedbelowifyouwant.However,atthetimeofwritingthisKangaroo
releaseismorecurrentthantheoneincludedinthecurrentRhinoWIP,soyoumaychooseto
installitanyway.Ifyoudo,youwillseesomewarningswhenstartingGrasshopper-youcan
simplyclickReplaceAlltodismisstheseandloadthisnewerversioninplaceofthedefaultone.

YoucaninstallKangaroo2alongsidetheoldKangaroo(0.099),andearlierdefinitionswillstill
work,buttheactualForceObjects/Goalsarenotcross-compatible,sinceKangaroo2wasa
completerewrite.
Iamtryingtophaseouttheoldversion-Ifthereissomefeaturefromitthatyouwantanditis
stillmissinginthecurrentKangaroo-letmeknowandIwilltryandaddit.Alsoifyouwantto
knowhowtoachievethesameresultassomeexampleorfilemadewiththeoldversion-please
letmeknowandIwilltryandshowsomethingsimilarinthecurrentone.

Pleasenotethatthisisstillawork-in-progressrelease,andallaspectsarestillsubjecttochange.

Examplefiles
Unlikepreviousreleaseswhereacollectionofexampleswasincludedwiththereleasedownload,
IamnowmaintainingacollectionofexampleKangaroodefinitionsonGitHubhere:
https://github.com/Dan-Piker/Kangaroo-examples
(TodownloadthewholecollectionclickCloneorDownloadandDownloadZIP)
ThiswayIcanmoreeasilymodifyandaddtothecollectionthouthavingtochangethisreleaseon
Food4Rhino,andyoucanknowyouaregettingthemostcurrentversionsofallthefiles.

Whatsnewinthisversion?

2.3.3-Fixedbugwhere6dofnodeswerenotupdatedinthezombiesolvercomponent

2.3.2-IncludesanewRigidPointSetgoal

2.3.1-Includesseveralnewgoals,includingsometosimplifycommonoperations,suchas
preservingtheedgelengthsofamesh,orapplyinggravitytoitsnodes.Also-theoutputofthe
Solvercomponentwillnowreconstructanydatatreestructurethatwaspresentintheinput.This
shouldsimplifydownstreamoperationswhereyouneedtoseparatetheoutputs.
ThisversionalsofixessomecompatibilityissueswiththeRhinoWIP.

2.3.0-includesafewmoregoalswhichusethe6dofnodesformechanicalmates.
AlsonewinthisversionareanEqualAnglesgoal,aBombgoal,aWindgoal,severalbugfixes,and
areorganizationofthegoalstab.
Also,theanchorgoalnowhasanoptiontosetthetargetlocationseparatelyfromtheinitial
location,whichcanbeusefulwhenyouwanttomoveitduringsimulation.
Thereisalsoanewsolvercomponenttoeasetheproductionofanimations.
Also,moreutilitiessuchasmeshprocessingtoolsareincludedwithKangaroo2,theintention
beingthatnewusersshouldnotneedtoinstalltheoldversion,onlythosewhohaveaparticular
needtoopenolddefinitions.

2.2.1-introduced6degreeoffreedom(6dof)nodes.Thisallowsformorerobustrigidbodies
andinteractionsbetweenthem,suchascollisions.

Installation

YouneedarecentRhinoservicereleaseandthelatestversionofGrasshopperinstalledfirst
(RhinoSR11,andGH0.9.0076atthetimeofwriting)
SofarthisreleaseisonlytestedonRhino564bitandmightnotworkon32bit.
Youwillalsoneedarecentversionofthe.NETframeworkinstalled
(http://www.microsoft.com/net)

Firstunblockthezipfile
(byrightclickingthefileinWindowsExplorer,andchoosing
properties.AtthebottomoftheGeneraltab,amessageabout
thefilebeingblockedmayappear.Ifso,clickunblock,and
apply),
thenunzipit.

Putthe2files(Kangaroo.ghaandKangarooSolver.dll)inthe
Grasshoppercomponentsfolder(replacingearlierversions
ofthesefilesiftheyexist).
Ifyouarehavingtroubleloadingthecomponents,double
checkthatbothofthesefilesareunblocked.(Unblockingthe
zipfirstshouldmeanthatthefilesafterunzippingareall
unblocked,butitseemsthisisnotalwaysguaranteed).
Notealsothatunblockingneedstobedonetoeachfile
individually,anddoesnotworkonmultipleselecteditems.

Afterinstalling,closeandreopenRhino,andlookfortheKangaroo2tabinGrasshopper.
YoumayalsofindyouneedtoturnCOFFloadingoff(bytypingGrasshopperDeveloperSettings
fromtheRhinocommandpromptanduncheckingthebox),thenrestartingRhino.
Ifafterfollowingthesestepsthepluginstilldoesnotload,pleaseletmeknow,withinformation
aboutanyerrormessages,andwhichversionsofWindows,RhinoandGrasshopperyouare
running.

License
Thissoftwareprovided'asis'withoutwarrantyofanykind,eitherexpressorimplied.
Theuseofthesoftwareisatyourowndiscretionandrisk,andtheauthorassumesnoliabilityfor
damagesofanykindarisingfromitsuse.
Youmayusethissoftwareforbothcommercialandnon-commercialprojects.
Youmaynotredistributethesoftwarewithouttheexplicitconsentoftheauthor.
Youmaynotreverseengineer,decompile,ordisassemblethesoftware.
Kangaroocopyright2010DanielPiker

IntroducingGoals

WhilepreviousversionsusedForceObjects, thesehavenowbeenreplacedwithsomethingcalled
goalsorgoalobjects.
Theseunifyandencompasstheideasofforces,energiesandconstraintsinasinglesystem.

Essentiallyagoalcanbeanyfunctionwhich,giventhecurrentpositionsofsomepoints,returns
sometargetpositionsitwantstomovethemto.
Kangaroocontainsmanydifferenttypesofgoals,whichcanbeappliedinanycombination,and
thesolverwilladjustthegeometryinordertomeetthemall.
Ifthegoalsconflictwitheachotherandnosimultaneoussolutiontoallofthemispossible,the
pointswillfindacompromisebetweenthem.Morespecifically,itwillminimizethesumoftheir
weightedsquareddistancesfromtheirtargets.Eachgoalcanbeassignedascalarvalueforits
weightingorrelativeimportance.

Becauseoftheirfastconvergence,thesegoalscanbeusedforinteractiveconstraintsolving,
includingbothunderandoverconstrainedproblems.However,unlikeconstraintsinthe
traditionalsense,thesegoalscanalsoincludethingslikeappliedloads,whichtryandmovea
pointinagivendirection,butcanneveractuallybemet.
Theycanalsoincludeelasticmaterialbehaviour,withthegoalgeometrybeingthereststate.
Anotherwayofseeingthesegoalobjectsisasquadraticenergyfunctionstobeminimized,with
thetargetpointsasthezerosoftheenergy.

Solvercomponent

ThesolvercomponentcanbefoundinthemainpaneloftheKangaroo2tab,andisthecomponent
whichcollectsallthegoalsandsolvesthesystem.
Thetimer/remotecontrolneededintheoldKangarooisgone.Thesolverautomaticallyrunsuntil
convergenceandthenstops.Forsimplesetupsthiscanbeprettymuchinstant,soyouwilljustsee
theequilibriumresult.ForlargerormorecomplexsetsofGoalObjects,itwilldisplaythecurrent
stateevery15-30msorso.

TheTolerancesettingonthesolvercomponentdeterminesthedistancebelowwhichmultiple
pointsgetcombinedintoasingleparticle.

-GoalObjectscannowbeaddedandremovedwithoutresetting.Coincidentpoints(withina
tolerance)willbecombinedautomatically.

-Thereisaspecial"Grab"GoalObject.Whenthisisconnected,itletsyoumoveanyofthe
simulationpointsintheRhinoviewportbyholdingdowntheAltbuttononyourkeyboardand
draggingwiththeLeftmousebutton.
(MakingitsoyouhavetoholdtheAltkeyisawayofstoppingthisinterferingwithmouseclicks
fornormalRhinooperation)

Note-WhenusingtheGrabobject,evenintopview,pointsmaygetmovedslightlyoutofplane,
thereforeifyouwanttokeepsomegeometryona2dplane,youshouldincludeanOnPlanegoal
actingonallthepoints.

Asofversion2.01theGrabobjectalsohasarangesetting,whichcontrolshowcloseyouneedto
clicktoapointtoselectit.

-ThereisnolongeranyneedtoFlattentheGoalObjectsinput,thisisdoneautomatically.

-IndividualGoalObjectshaveanoptiontooutputsomedataaftertheoptimization.Thesecome
outoftheOoutputoftheSolvercomponent.Thiscanincludegeometrytodisplay(currentlythe
Lengthobjectoutputsaline,andthePlanarizecomponentoutputsanumberforthetwistamount
ofeachface),buttheideaisthatthisisageneralholderforanyinformationyoumightwantto
getoutfromacustomGoalObject,suchasstressesetc.Theoutputscomeoutasaflatlistinthe
ordertheGoalObjectsarereadin.Infuturetheplanistopreservethetreestructureherefor
easierorganizationofresults.

-TheShowobject(intheMainpanel,withthelightbulbicon)isusedtoattachadditionalgeometry
tobedisplayedtothepointsinvolvedinthesimulation.Itworkswithlines,polylines,arcsand
meshes.

-Weighting/Stiffness/Strengthvaluescanbesetarbitrarilyhighandthesystemshouldremain
stable(thiswasamajorlimitationofearlierversions,particularlyforsimulationofrealmaterial
stiffness).However,ifyouhaveextremelyhighratiosbetweenthestrongestandweakest
constraints(like1e12and1e-12),thenmovementtowardstheweakergoalwillbeslower,andit
maytakealongtimetoconverge.
Ifyouneedonehighprioritygoalmuchstrongerthanothers(sometimesdistinguishedashardvs
softconstraints),butstillneedthelowerprioritygoalstoinfluencetheform(suchaswhen
planarizingthequadsofamesh,butalsowantingtheoverallformtobesmooth),itis
recommendedtostartwithallgoalsatmoderateratioswhilecreatingthegeneralform,then
increasetheweightingofthehardconstraintuntilitisenforcedasexactlyasrequired.

Goalcatalogue

Whatfollowsisabriefdescriptionofeachofthecurrentlyavailablegoalobjectsin
Kangaroo2.
 Someofthesewillbefamiliarfromtheoldversion,whilemanyarecompletelynew.Not
alltheforceobjectsfromtheoldversionhaveagoalequivalenthereyet,buttheintentisto
eventuallyaddallofthemandmore.Iamaddingnewgoalsallthetime,andwelcomesuggestions
formore,andyoucanalsoscriptyourown(seethesectionattheendaboutscriptingKangaroo).

Anchor
Thiskeepsaparticleinitsoriginallocation.

AnchorXYZ
AnAnchorwithoptionsforwhichoftheworlddirectionstorestrainthepointin.For
example,toallowapointtomoveonlyintheworldXYplane,youwouldset
X=false,Y=false,Z=true.
ToallowittomoveonlyalongtheX-axis,youwouldsetX=false,Y=true,Z=true.

Length
Triestokeep2pointsagivendistancefromeachother.Notethatifnoinputforthelength
issuppliedtothecomponent,itwilltakethestartinglengthasthetargetlength(insteadof
defaultingto0asinearlierversions).
Thelengthgoalobjectcanalsobeseenasalinearlyelastic1Dfiniteelement,andits
deformationsunderloadcanbeassignedrealquantitativemeaning,bysettingthestrengthtothe
springconstantinN/m,calculatedasEA/L,whereEistheYoungsmodulusofthematerialinPa,
Aisthecross-sectionalareainm2,andListherestlengthinm.

ClampLength
Keepsthedistancebetween2pointsbetweengivenbounds,butappliesnoforcewhenthe
distanceiswithintheselimits.ThisissimilartotheSpringCutoffsinpreviousversionsof
Kangaroo.

EqualLength
Triestomakeasetoflinesequallength.ApplyingoneEqualLengthgoalforthe4sidesofa
quad,andanotherforits2diagonalscanbeawayofmakingitmoresquare,sometimesa
desirablequalityinmeshes.

Load
Aforcevector.ThelengthofthevectoristhemagnitudeinNewtonsoftheappliedload.

Coincident
Keeptwopointsatthesamelocation.Thisisequivalenttomakingazerolengthgoal
betweenapairofpoints.

Angle
Keeps2linesegmentsatagivenanglerelativetoeachother.Ifnoangleissuppliedthe
startingangleisused.Thelinesegmentscanbedisconnectedortheycanshareacommonpoint,
inwhichcasethissimulatesthebendingofanelasticrodofcircularcross-sectionwithouttorsion.
TheformulationofthebendingenergyusedisfromAdriaenssensandBarnes2001.Toassign
valuesbasedonrealmaterialproperties,useaStrengthinputofE*I,whereEistheYoungs
modulusinPa,andIisthesecondmomentofareainm.

ClampAngle

LikeAngle,exceptitallowsyoutosetupperandlowerbounds,betweenwhichitwillnotapply
anyforce.

Direction
Thisrotatesalinesegmenttoalignitwithagivenvectordirection.Ifnodirectionis
supplied,itwilltaketheclosestofthe+/-worldXYZdirections,andcanbeusedtosnapgeometry
toorthogonal.

Floor
KeepsparticlesfrompassingbelowZ=0

LengthSnap
Snapsthelengthofalinetotheclosestwholenumbermultipleofagivenvalue

AngleSnap
Snapstheanglebetween2linestotheclosestwholenumbermultipleofagivenvalue

Planarize
Flattenseachofthequadsinamesh.

CoPlanar
Pullsasetofpointstowardstheirbestfitplane.Thiscanactonanynumberofpoints,but
ifyouhaveonlysetsof4,usePlanarizeinstead,asitwillbefaster.

CoSpherical
Pullsasetofpointstowardstheirbestfitsphere

CoLinear
Pullsasetofpointstowardstheirbestfitline

OnCurve
Pullsapointtowardstheclosestpointonagivencurve

OnPlane
Pullsapointtowardstheclosestpointonagivenplane

OnMesh
Pullsapointtowardstheclosestpointonagivenmesh

Hinge
Bendingresistancebetweenapairofadjacenttriangles.Usefulforsimulationofplates
andshells.
TheformulationofthisenergyisbasedonTachi2013

PlasticHinge
 Similartothehingedescribedabove,exceptanelastic/plasticthresholdangleisgiven,and
whenbentmorethanthis,thematerialdeformsplastically.

CyclicQuad
Triestomakethe4verticesofaquadlieonacommoncircle.Shouldbeusedin
conjunctionwithplanarize.Canbeusedforgeneratingcircularmeshes,whichhaveusefuloffset
propertiesforbeamstructures.

TangentIncircles
Adjuststheverticesofapairofadjacenttrianglessothattheirincirclesbecometangent.
Thiscanbeusefulforgenerationoftorsionfreebeamlayoutsandotherstructures.
EnergyfromHoebinger2009

PlasticAnchor
Likearegularanchor,thisactsasanelasticforcetryingtokeepaparticlefixedata
particulartargetposition.However,unliketheregularanchor,thetargetpositionofa
PlasticAnchorwillmoveifitispulledhardenough.TheparameterLsetsthedistancelimitat
whichtheanchorwillstarttoshift.
Itcanbethoughtofasactinglikethestaticfrictionthatkeepsobjectssittingonatablefrom
slidingaroundwhenpushedonlylightly,exceptinsteadofasurface,thereferenceisabsolute3d
space.
Thiscanbeusefulforsculptingapplicationstostopparticlesfromkeepingdrifting.For
example,whenyouhaveameshwithsmoothingforcesactingonit,ifleftalone,itwill
continuallyshrinkandflattenitselfout,evenifthesmoothingforcesaresmall.Applyinga
PlasticAnchortoeveryvertexofthemeshwillallowthesmoothingtoroundouttheshape,but
oncethesmoothingforceislessthantheplasticlimitoftheanchoritwillstopmoving.

PlasticLength
Thiswillbehaveelasticallyatfirst,likearegularLengthgoal,tryingtokeepapairof
particlesacertainrestdistanceapart,butifstretchedorcompressedbeyondthegivenlimit,this
restdistancewillchange,simulatingplasticdeformation.

PolygonArea
Pushesthesegmentsofaclosedpolylineinwardsoroutwardssothattheyenclosea
planarshapeofthegivenarea.
Note-thisisa2dgoal,andworksonlyintheXYplane.

Smooth
UniformLaplaciansmoothing,roundsanysharpfeaturesofamesh.
NotethatSmoothactsonlyoninternalvertices,anddoesnotaffectthenakedboundariesofa
mesh,andtheseoftenneedtoalsobefixedorsmoothedinsomeway.

Transform
Thisisagoalwithmanypotentialuses,asitmaintainsagiventransformationbetweena
pairofpoints,soitcanpreservevarioustypesofsymmetry,periodicboundaryconditionsetc.
Grasshoppertransformationobjects(suchasreflection,rotation,translation,scaling...)havea
Transform(X)outputwhichcanbeusedastheinputhere.

RigidBody
Thistreatsagivensolidmesh(youcanalsosupplyaBrepasinput)asarigidbody-
meaningithas6degreesoffreedom(3fortranslationand3forrotation),andthisrigidbody
motionistreatedseparatelyfromanydeformation.Youcanattachpointsanywhereinspaceto
therigidbody,andtheywillstayatthisrelativepositionasthebodymovesandrotates(note
theseattachedpointscanbeonorinthesolid,buttheydonotneedtobe).
Mechanicalassemblymatingconstraints,suchasrevolutehinges,pin-joints,slidersetc,
canbeappliedbyattachingthesamepointsto2rigidbodies.Forinstance,if2bodiesbothhave
the2endpointsofasinglelineasattachmentpoints,thislinebecomesarevolutehinge.Ifthey
shareonlyonepoint,thiswillbecomeapin-joint,etc.Theserigidbodiesarearelativelyrecent
addition,andstillsubjecttofurthertesting.

Collide2d
Collisionsbetweenclosedpolygonsinagivenplane.

Collider
Collisionsbetweenamixofthickenedlinesegments(capsules)andspheresofvariousradii
(usingabroad-phasecollisiontospeedthingsup).

SphereCollide
Collisionsbetweenequalsizedspheres,optimizedforspeed.

SolidPointCollide
Collisionsbetweenpointsandaclosedsolid.Thesolidcanbesuppliedaseitherameshor
aBrep.Thereisanoptionforwhetheryouwanttokeepthepointsinsideoroutsidethesolid.
Fromversion2.02,thiscomponentalsoincludesanoptionforwhethertouse
1-way(Unidirectional)or2-wayinteraction.
IfUniDirectional=True,thesolidisusedjustasaninput,whichyoucanchangeormoveduring
simulation,butitisnotitselfaffectedbythephysics(IthinkMayacallsthesepassivecolliders,
butIfeelUniDirectionalismoredescriptiveofhowtheyactuallywork).
Thedefault2-waybehaviourcanbeusedforcollisionswhereyouwantthemeshtoalsobe
movedanddeformedbythecollisionforces.

Volume
Controlthetotalvolumeofamesh.Thiscanbeusedforinflatables.

MagnetSnap
Appliedtoacollectionofpoints,ifany2pointsgetclosertogetherthantheRangeR,they
willbesnappedtogether.

SoapFilm
Anareaminimizingelement,whichcanbeusedforfindingminimalsurfaces.Sincethisis
derivedfromcontinuummechanics,theresultingshapeisnotdependentonthedensityofinitial
meshingused,asisthecaseifusingzero-lengthspringsfortheedges.However,becausethese
soapfilmelementsproduceforcesonlyinthenormaldirectionofthesurface,theyusuallyneed
someothergoalstokeepthepointsfromdriftingorthetrianglesbecomingtoodistorted.Insome
casesthiscanbeachievedbyallowingfreedomofthenodesinonlyonedirection.Alternatively
youcancombinethemwithtangentialsmoothing(seebelow).
 TheSoapFilmgoalobjectrequiresalistof3pointsasinput.Sotoapplytoamesh,you
musttriangulateit,andinputthe3pointsofeachface.(Note-takecareifusingthefacepolyline
boundarieshere,asexplodingatrianglepolylinewillgive4vertices,becauseitcountsthefirst
onetwice.Instead,takethestartpointsofthe3segmentsoftheexplodedpolyline)
Soapfilmelementsareusefulifyouareaftertruezero-meancurvatureminimalsurfaces,
ormembraneswherethestressesarethesameinalldirections.However,theyareabitmore
complextouse,andinmanycases,simplytakingthemeshedgesasLengthgoalswithatarget
lengthofzeroisaneasiermethodoftensileform-finding.

TangentialSmooth
TypicallyusedincombinationwithSoapFilmelements.Thissmoothsthevertexpositions
ofamesh,butonlyinthedirectionsacrossthesurface,withnoeffectinthesurfacenormal
direction.Soitkeepspointswelldistributed,butshouldnotaffecttheoverallshape.

ScriptingKangaroo

AbigpartofthisrewritehasbeenmakingKangaroomoremodular,andallowinggreater
customizationthroughscripting.Documentationforthislibraryisslimatthemoment,butisa
workinprogress,andIwillalsobehappytohelpontheforumifyouhaveanyquestionsinthe
meantime.

Definingacustomgoalobjectisassimpleasmakingaruleforasetofparticlestellingthem
wheretomoveto(thisisincontrastwithothersystemswhereyouneedtoprovidefunctionsfor
firstorsecondderivatives,ordifferentialcoordinates).Thehopeisthatthissimplicitywillallowa
widevarietyofpossiblegoals.

Theexamplesfolderincludessomeexamplesofcreatingcustomgoalobjectsandcustom
iterationsusingC#(thoughyoucanalsouseVBorPython).
TheKangaroolibraryisseparatefromtheGrasshoppercomponents,anddoesnotdependonany
GHfunctions,soyoucanalsoreferencethelibraryandcallthefunctionsfromscriptsrunning
directlyinRhino.