Results 1 to 3 of 3
Like Tree11Likes
  • 6 Post By amoursol
  • 1 Post By josephpeel
  • 4 Post By amoursol

Thread: An Introduction to DesignScript

  1. #1
    Senior Member amoursol's Avatar
    Join Date
    November 21, 2012
    Location
    London, United Kingdom
    Posts
    500
    Current Local Time
    07:53 PM

    An Introduction to DesignScript & Replication Guides

    DesignScript is a fantastic piece of the Dynamo puzzle.

    It allows you to clean up messy definitions, nest node objects within each other and cycle through data using Replication Guides in a pretty efficient manner.

    Node2Code (Dynamo 0.8.2 and above) will allow you to convert standard nodes to DesignScript, but will do so in a rather inefficient manner.

    The basics of DesignScript are as follows:

    There is a triumvirate of Creators (+), Queries (?) and Actions (Zap), that mirrors the node style in the library.

    An Introduction to DesignScript-library.jpg

    Creators will colour themselves green as shown below. Any time you partially type in a Creator, it should allow a dropdown menu showcasing the options you have.

    An Introduction to DesignScript-creator.jpg

    Creators require Creation Methods. This is how your creator is to be formed and are coloured blue. A couple of examples are shown below:

    An Introduction to DesignScript-creator_method.jpg

    After you have your chosen Method (Also available by a dropdown menu after your dot nomenclature), you need to put in values that the method requires to create your creator. These are always bound by brackets, and when you type in your open bracket you get an input prompt. You can cycle through this prompt with the arrow keys (For multiple creation methods). In the following example we can create a point by either a simple X and Y, or by X, Y and Z.

    An Introduction to DesignScript-creator_method_values.jpg

    The prompt will tell you what type of data needs to go in, as well as give you the name.

    After we put in our values, we close the Creator off with a Close Bracket and Semi-colon. The semi-colon wraps up that bit of code and calls it a day and is required for all DesignScript code.

    An Introduction to DesignScript-creator_method_values_closed.jpg

    That's the basics of Creators. But usually we need to use this data later on in the piece (Rather than simply using it's wire output), so we give it a name. After giving it a name we can call that thing by its name and apply queries or actions against it.

    This is achieved by giving it a name followed by the equals sign as shown below:

    An Introduction to DesignScript-creator_name.jpg

    Once we have this we can move onto our second item in the triumvirate, Queries, which also show up blue. It will, however, only show up blue when fully completed and written with the correct Title Casing.

    Queries are achieved by putting a dot after a proper thing and subsequently writing out the query. Unfortunately, there is no dropdown list for these. You have to either know, or check the library - but it becomes second nature pretty swiftly.

    In the case of Queries you don't use brackets (As it's simply querying and you don't need any values for a creation method).

    An example of a query is shown below, where we want to get the Z-Value from our point, or get the Number of Cuves from a polycurve:

    An Introduction to DesignScript-query_zvalue.jpg An Introduction to DesignScript-query_numberofcurves.jpg

    Any Query for that creation method type that can be done by nodes, can be done by code. If in doubt either use Node2Code to change a node or hover over the node in question and the DesignScript prompt will appear.

    Our last triumvirate object is the Action.

    This is where we want to do something to a thing.

    As an example, we'll add a vector to our original point.

    To action something, you also need to use the dot nomenclature, but as with queries, you don't get a prompt sadly, and will also show up blue. It will, however, only show up blue when fully completed and written with the correct Title Casing.

    As noted previously in the creation section, we will need a method as we have to tell our action how to action. For this example we'll be using Point.Add as our Action Method.

    An Introduction to DesignScript-action_method.jpg

    Our chosen method will require values for it to action. So, as with our creator method, we need to use brackets to define these inputs. We need a little background knowledge on how our action works however as it won't give us prompts (Unfortunately).

    In this case you'll need to know that the Point.Add command requires a vector. So we can either nest a creator within our action, or create a new line and define our vector with a name. Either will accomplish what we desire - which is moving our point up by 10 units.

    An Introduction to DesignScript-action_method_value.jpgAn Introduction to DesignScript-vector-point-add.jpg

    You can also nest a whole bunch of methods together - and there are a couple of examples below courtesy of the extremely helpful folk at the Dynamobim.com forums (Namely for the images below: Dimitar Venkov, Vikram Subbaiah and Eprocauno).

    An Introduction to DesignScript-dimitar_venkov_designscript_diamond_grid.png An Introduction to DesignScript-dimitar_venkov_designscript_filterbybooleanmask.png An Introduction to DesignScript-eprocauno_stepped_list_definition.jpg An Introduction to DesignScript-vikram_subbaiah_colourisationbydistance.jpg An Introduction to DesignScript-vikram_subbaiah_designscript_if_statement.jpg
    Last edited by amoursol; December 17th, 2015 at 02:51 PM. Reason: Edit: Clarity

  2. #2
    Forum Addict josephpeel's Avatar
    Join Date
    May 3, 2012
    Posts
    1,080
    Current Local Time
    08:53 PM
    Thanks! Good to have a basic explanation of the syntax etc.
    amoursol likes this.

  3. #3
    Senior Member amoursol's Avatar
    Join Date
    November 21, 2012
    Location
    London, United Kingdom
    Posts
    500
    Current Local Time
    07:53 PM
    An Introduction to Replication Guides:

    NOTE:
    Replication Guides have changed behavior. Please refer to the following thread, and specifically the reply by Zach Kron, until this Introduction is updated: http://dynamobim.org/forums/topic/re...ged-behaviour/

    Replication guides are how we control list operations in DesignScript. While nodes have lacing, DesignScript has Replication Guides. They can function in the same way, but Replication Guides offer a much greater degree of control over your data.

    Replication guides are described by the Dynamo Language Guide as follows:

    "While range expressions offer a convenient means of generating one dimensional collections of elements, replication guides offer a convenient means of generating two and three dimensional collections.

    Replication guides take two or three one-dimensional collections,and pair the elements together to generate one, two or three dimensional collection. Replication guides are indicated by placing the symbols <1>, <2>, or <3> after a two or three collections on a single line of code."


    Jostein Olsen also explains replication guides thoroughly on his blog post Replication Guides for Semi-Dummies by utilising points as a case study.


    2D Array Example:

    Using a simple test case of two equal length lists of data, we can explore how these work:

    List A = A number range from 1 to 10, stepping by 1.
    List B = An alphabetic range of 10 characters ('a' to 'j').

    Baseline Functionality:

    Base line functionality of nodes in Revit defaults to 'shortest lacing', and in Code Blocks (Or DesignScript) this is also the case. So if we want to add two lists together, without replication guides, we'll get the following output.

    An Introduction to DesignScript-replicationguides_1.jpg

    Joining lists in the default manner will simply pair the first item of List A with the first item of List B and result in an output list of 10 items, concatenated from List A and List B.

    Single Replication Guide:

    Adding in a single replication guide, either after the input of List A or List B, will change how the data of one list interacts with the other.

    Whatever list input has the single <1> replication guide next to it, will become the driving or primary list.

    If List A is the driving list, this single replication guide will take every individual item from List A (Our numbers) and pair them with the items from List B (Our letters). This will result in individual sublists of 1a, 2a, 3a ... 4c, 5c, 6c ... 8g, 9g, 10g and so on. We will have every single combination of our primary list with that of our secondary list.

    An Introduction to DesignScript-replicationguides_2.jpg

    If list B is our driving list, it will iterate through every option by having the List B items as driving the data. Notice that as our Code Block data is being added together by 'List A' + 'List B', this formatting persists after the addition of the replication guides. With List B being the driving list, the resultant individual sublist data will be of the format 1a, 1b, 1c ... 3d, 3e, 3f ... 10g, 10h, 10i and so on.

    An Introduction to DesignScript-replicationguides_3.jpg

    Matching Replication Guides:

    In both of the replication guide examples showcased below, the data arranges itself as the Baseline Case. This is because we are telling each list that their primacy is equal.

    An Introduction to DesignScript-replicationguides_4.jpg


    An Introduction to DesignScript-replicationguides_5.jpg

    Double Replication Guides:

    Adding in a double set of replication guides, one after the input of List A and one after the input of List B, will again change how the data of one list interacts with the other.

    Whatever list input has the higher number replication guide next to it, will become the drivinglist and this will tier down in order. So a replication guide of <1> is subservient to a replication guide of <2>, and a replication guide of <2> is subservient to a replication guide of <3> and so on.

    In a double replication guide situation, having List A being the primary list results in the Numbers being dominant.

    An Introduction to DesignScript-replicationguides_6.jpg

    If List B is the primary list, the results will have the Alphabetic characters as dominant, or driving.

    An Introduction to DesignScript-replicationguides_7.jpg

    Longest Lacing:

    You'll notice so far that we haven't been able to replicate the longest lacing option we have available in node form.

    There is a special syntax for this in Replication Guides that uses the form of <1L>, where the capital 'L' (Lowercase will fail) demarcates longest lacing. Longest lacing replicates the final item of the shortest list across the additional items of the longest list.


    An Introduction to DesignScript-replicationguides_8.jpg
    Image credited to Andreas Dieckmann




    3D Array Example:

    The data type within Replication Guides matters: Our 3D array example cannot use the above format as a series of a<1>+b<2>+c<3> will simply result in null values. The data is too simple. For a 3D array we need to use ranges.

    We'll use Points to demarcate how replication guides work in a 3D setting.

    No Replication Guides:

    The default functionality, without replication guides, will give us a points list that matches the first input for each of the X, Y and Z variables, and cycles through list the lists matching index to index.

    The result of this is a series of points that run from 0,0,0 to 1000,1000,1000 (x,y,z).

    An Introduction to DesignScript-revitforum_replicationguide_01.jpg

    Single Instance of <1>:

    If we put a replication guide after a single variable (Either X, Y or Z) we'll allow that input variable to be dominant and it will run through it's list of inputs as the driving list, creating every single combination of that list by matching the first item of the secondary and tertiary variables.

    An Introduction to DesignScript-revitforum_replicationguide_02.jpg

    Within the base nodes, to follow our example, you can use a Point.ByCoordinates node of which has three lacing options: Shortest, Longest and Cross-Product. Both shortest and longest lacing will match with the default DesignScript variant. As shown below, cross-product is the only lacing option that will allow you to switch up your data.

    An Introduction to DesignScript-revitforum_replicationguide_03.jpg An Introduction to DesignScript-revitforum_replicationguide_04.jpg

    Double Instance of <1>:

    The single instance of <1> has already given us 3x options of how our data is formatted. If we choose to put another replication guide of <1> after a second input variable, we force our data to push through both replication guided lists, while pairing them with the first item of the non-replication guide list.

    An Introduction to DesignScript-revitforum_replicationguide_05.jpg

    As previously, putting a replication guide of <1> after every input variable will result in formatting that is the same as no replication guides.

    An Introduction to DesignScript-revitforum_replicationguide_06.jpg

    Note: In all of the 3D array examples above, the number <1> can be substituted for <2> or <3> and so on - with the caveat that they are all the same number.

    And Then We Get Funky:

    The higher the number in each replication guide, the more dominant that replication guide is. So when we start adding in multiple replication guides, we start formatting our data in a tiered fashion.

    If we choose to put a <2> beside our Y input variable and a <1> next to our X input variable, we'll get a 2D array of points, in the Y axis as the dominant replication guide, replicating a 2d grid of points by using each of the X input variables numbers. The Z input variable remains at zero (first item in the list) as we haven't told this data to 'join the party'.

    An Introduction to DesignScript-revitforum_replicationguide_07.jpg

    If we choose to put the <2> replication guide by the X input variable and a <1> next to our Y input variable instead, ostensibly our 2D array doesn't change but the way the data is formatted does: the driving list is now the X variable list.

    An Introduction to DesignScript-revitforum_replicationguide_08.jpg

    If we choose to put a replication guide next to the Z input variable instead, the quote unquote "2D" array will become a pseudo "3D" planar array.

    As previously, if we choose our secondary tier to be the Y variable, we'll get our planar array in the YZ-axes or if we choose our secondary tier as the X variable, we'll get our planar array in the XZ-Axes.

    An Introduction to DesignScript-revitforum_replicationguide_09.jpg

    If we choose to bring all three input variables to the party, we start getting more variations on data formatting. Instead of a vertical planar array, we now have a truly 3D planar array with our chosen tiered structure demarcating the dominant and subversive nature of the data formatting.

    An Introduction to DesignScript-revitforum_replicationguide_10.jpg


    As previously using replication guides in the form A<1>,B<2>,C<1> is the same as A<2>,B<3>,C<2> as its the hierarchy of the replication guide numbers that matters.

    Plumbing the Depths:

    The final variant to explore is that of using three tiers of replication guide number hierarchy.

    Ostensibly, when using replication guides to create a cross-product result (Every single possible option), the graphics will look the same for our points example. The data, however, will be based off the dominance of the replication guides.

    An Introduction to DesignScript-replicationguides_15.jpg

    The location of the Points don't change to the eye - but they way they are created does.
    Last edited by amoursol; March 15th, 2016 at 08:29 AM. Reason: Addition: Replication Guide behavior changed. Link added to Zach Kron's post on the subject.

Similar Threads

  1. What Revit Wants: Introduction to COBie
    By luke.johnson in forum Blog Feeds
    Replies: 0
    Last Post: May 23rd, 2014, 07:45 AM
  2. Replies: 0
    Last Post: February 24th, 2014, 09:15 AM
  3. Revit Detail: 13.0 Modern House - Introduction
    By Blog Fetcher in forum Blog Feeds
    Replies: 0
    Last Post: June 30th, 2011, 12:30 PM
  4. Introduction: Church Renovation Project
    By rkitect in forum Rendering and Gallery
    Replies: 9
    Last Post: May 13th, 2011, 01:35 PM

Tags for this Thread

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •