Monday, May 21, 2018

Documentation for today's programmer

When creating documentation, whether for a project, lab, or technical, you would have run into the challenge of needing to move that documentation to different formats: PDF is a popular one, but perhaps also HTML, particularly if your company uses a wiki for such things. At nsquared, we found that this movement of documents can get frustrating, not only because they do not always come across cleanly, but also because if they are different, you then have to maintain a bunch of different documents. Time to solve this, using tools which are freely available: Markdown, Pandoc, and PowerShell.

The solution is reasonably simple. You can still write your document up in your favourite word processor, however, keep the formatting to a minimum (avoid anything more complex than bold, italics, and hyperlinks; also, you can add images, but do not do it in your word processor). Once you have your file ready, save it out as a .docx, so that we can get underway in earnest. The first part covers converting your document to the Markdown format.

Steps to convert from docx to Markdown:
1. Download and install Visual Studio Code.

  • - We will use this to edit your document later, but essentially this will be your go to program very soon.
2. Download and install the Pandoc installer (download the latest Windows ‘x86_64.msi’ file).
  • - Pandoc is a freely available program online, which will handle the conversion of your documents. It supports a host of outputs, including: docx, HTML, Markdown, PDF, latex, and txt, just to name a few.
3. If you are running Windows 10, you will already have PowerShell available to you. This solution is written for Windows, though is transferable to Apple Mac, via the use of Terminal. Once you are ready, launch PowerShell (found by typing 'power' into the search of the Windows menu).
4. You now need to navigate PowerShell to the location of your document. Generally, it will start in your user folder (C:\Users\YourAccount). You can use the 'cd' command, plus the path of your document to get there quickly:

  • - Type: cd 'C:\Users\YourAccount\Documents'.
  • - Make sure to replace the path section with the location of your document (the above uses 'Documents' as that location). 
5. With the above completed, you will notice that the path that PowerShell is using is what you just typed - this means that it is now using this location as the point from which to execute commands.
6. Now it is time to utilise Pandoc. In PowerShell, type: pandoc 'YourDoc.docx' -f docx -t markdown -s -o ''

  • - Make sure to substitute 'YourDoc' with the name of your current document, and update 'YourNewDoc' to have a name which you want, for your converted file.
  • - If you want to know about the commands available for Pandoc, make sure to visit their documentation page.
7. With that all in place, press the Enter key on your keyboard to run the command.
8. Your document will be converted to Markdown (though retaining the original document, though you will not need it by the end, so do with it what you like).
9. You have successfully converted your document from .docx to Markdown, the next part is to update your document using Markdown.

Steps to update your Markdown document for easy conversion:
1. Open Visual Studio Code. Once open, you will be presented with a (mostly empty) window. This might look familiar in part, if you have used any other Visual Studio program; Visual Studio Code is the light weight version, and it is remarkably powerful, and allows you to easily write in many programming languages.

2. Click File > Open File, and then browse your files for your new Markdown file (we are opening it in VS Code).
3. With your file now open in Markdown, you will notice that it is looking very plain. This is the power of Markdown, it utilises only the most basic of formatting, however, this allows it to easily be converted into other formats.
4. Here is an excellent cheat sheet of how Markdown works. Have it at the ready, for the next few steps.
5. Now you will need to open the preview page (which shows you what your document will look like with Markdown applied). With your document open, navigate to the top right, and click the split window icon, with the magnifying glass in front of it:

6. You will be presented with a panel to the right of your Markdown document, which is showing you what the output will be. You will notice, all the Markdown tags (#/*/---/```) are gone, and just plain text appears, with light formatting.

7. Now, using the cheat sheet as a guide, update your Markdown document, so that it presents how you would like it.
8. With your Markdown complete, close Visual Studio Code, because, you are ready for further conversion!

Steps to convert your Markdown to HTML:
1. Open PowerShell once more, and navigate to your Markdown document:

  • - Remember to use the ‘cd’ command, and the path to your document – cd 'C:\Users\YourAccount\Documents'
2. Once PowerShell is in the same location as your Markdown document, use the following command to convert from Markdown to HTML:
  • - Pandoc '' -f markdown -t html -s -o 'YourNewWebpage.html'
3. Your document is now in HTML! If you had images and set them up correctly (according to the cheat sheet), they will have come across cleanly, creating a ‘media’ folder along the way, to use with your new webpage.

As you will realise, from now on, you simply need to maintain your Markdown document, and then you can convert it; as mentioned previously, this works for PDF and docx too, so you can always produce those formats if you need them.

This is the start of your Markdown journey, though, expect to continue and go further. Through using Pandoc, and PowerShell, you could put together a PowerShell script to automatically convert your latest Markdown document to HTML, so that you can keep working on your documents, without worrying about the export process. This is an excellent workflow and may help you increase efficiency!

Elliot Moule

Tuesday, May 8, 2018

Bringing your 3D Models into Unity

When you are working across multiple programs in technology, it’s important for any designer to be aware of what file formats are suitable for the program you’re using. There is nothing worse than working long and hard on making something look great in one program, and having an error on it when dragged into another!

3D is lots of fun and very straight forward to make simple models to deck out any scene in Unity, so I’m going to walk you through a simple procedure of exporting for a 3D model into Unity. My preferred 3D modelling software is Autodesk Maya but you can use any you wish, as long as you can export the model into an FBX file.

Why .fbx?
An fbx file is a 3D asset exchange format that is compatible with many 3D tools. It also enables you in most cases to save your materials on the object if desired. As opposed to an OBJ file, your capabilities are much larger.

Getting started:
Jump into Maya and create your model. I have made a simple lamp to use as an example. Note: you want your model to be on the lower side of the poly count. To keep track of the count, select Display > Heads Up Display > Poly Count. The count will appear in the top left corner.

You can apply your materials to the object in your 3D software, OR Unity. For the sake of showing you how to do so in Unity I’m going to leave my model without a material in Maya.

A few things to check before exporting:
- It is a good idea to combine your meshes. You can do this by holding the mouse and dragging a box over all the objects and selecting Mesh > Combine.
- The ‘Up Axis’ should be set to ‘Y’.
- Your model is on the ground plane, with all location and rotation values set to 0 in the ‘Attribute Editor’ panel.

Getting your model export-ready is very straight forward. Ensure the alignment is correct and everything is squared-out and facing forward toward the positive Z-Axis. When you’re ready, go to File > Export All. Select FBX under ‘Files of Type’ to export in the correct file format. Name your file and place it somewhere you can easily access when you open up Unity to import the object.

Once you’re in Unity:
Once you’ve got a new or existing scene set up in Unity, simply drag and drop into the Assets panel. Once you can see your model, drag it into your scene. You can then right click in the Project panel and click Create > Material. Now for the fun part! You can drag and drop a PNG if you’d like, or select a colour from the top right Inspector panel. It’s here you can also customise your material by toggling between the X and Y options in the tiling section.

So there you have it!
A basic guide on how to get your 3D objects into Unity correctly as well as a little bit of customisation. Happy designing!

Jacqui Leis