HitchHiker

The HitchHiker’s Guide

HitchHiker has been updated – If you want to see the newer features navigate to

http://lonerobot.net/?p=1003

dialog

So what is it?

HitchHiker is a VB DotNet / 3dsMax User Control and is designed to provide automatic thumbnailing of directories containing a variety of media types. This can be employed in a variety of situations as it is designed to provide a fast and simple method of building a fully functional asset browser or similar media browsing utility. HitchHiker only needs instruction of which directory to look in, and it will build an interface that allows you see the folder’s contents in a choice of different views. It is easy to configure the display layout according to presets accessible in the control, or is fully customisable with a bit of scripting to look the way you would like. It’s a DotNet equivalent to Rollout Creator. The advantage of using something like this is that the display logic is already built in, leaving the task of integrating it into 3dsMax a simple one, even for someone with very little scripting experience. It is also able to load image types not normally available to a DotNet assembly.

Usage

HitchHiker inherits the MaxUserControl class, a DotNet class that Autodesk added to 3dsMax as part of their DotNetSDK. It also uses the functionality of the ManagedServices.dll included in 3dsMax. This means that you can only use this user control in the 3dsMax environment.

It is compatible with both 32 bit and 64 bit versions of max, but you will need 3dsMax 2010 in order for it to work.

Hitchhiker is free, all I would ask is that if you use it for something useful or cool, give a credit as to where it was from!

Supported Formats and Third party Image Libraries

ftypes

If you are familiar with how windows uses various image file formats, you’ll notice that there are several image types that windows will not open, but are useful to a 3D Artist. Most notably this is Targa, RPF and PSD. In order to open these file formats via DotNet, you would usually be tied to using a custom image library such as FreeImage or ImageMagick. This would add an extra deployment assemblies. However the biggest issue is when used on a 64 bit platform. I have found it difficult to find an x64 compatible image library that will let me integrate into Visual Studio and 3dsMax without a large configuration headache.

With this in mind, HitchHiker uses a two step approach.

Image formats that windows natively opens, like JPG, PNG and TIF are generated as part of a threaded GDI+ process within the control. These are subsequently fast to return, and keeps the UI thread of max separate.

Non-windows formats are opened in 3dsmax by registering a bitmap loading function with the MaxScriptSDK methods in the managedservices.dll. The 3dsmax bitmap is then passed back to the control via the clipboard as a DotNet bitmap where they are processed in a non threaded environment. The thumbnailing routine is still performed in the assembly rather than Max as by this point the bitmap is in the correct bitmap format for the control to use. You are simply using the 3dsMax Image readers to plug the gap in DotNet file types.

This is all made possible via the enhancements to the managedservices.dll.

It struck me as odd that I was struggling with 3rd party image libraries, 3dsMax had the means to open these non-compatible formats. However it wasnt an option until 3dsMax 2010, when the MaxscriptSDK was introduced into the DotNetSDK. This is my first control i have built that registers all of the 3dsMax image function handling via the DotNet control instantiation. I have talked about this on my site before so you will hopefully be aware of some of the things you can do with it.

See the diagram for more details –

flowdiag

This is the neatest way of integrating custom Image types into DotNet I can think of for the time being – I would hope in the future, Autodesk would include a method for this in the DotNetSDK as it would significantly enhance custom control and UI development.

Hithiker needs no external image dependancies, I have embedded the icons and UI images into the resources.resx file in the assembly.

_______________________________________________________________

How to Use HitchHiker

Hitchhiker is a DotNet UserControl and the easiest way to use it is on a rollout as a DotnetControl. You will need to load the assembly first, using the dotnet.loadassembly method, pointing it to the directory that you have copied hHitchHiker to.  A simple rollout integration is as follows –

rollout HitchHikerRollout “” width:240 height:270
(
dotNetControl HitchHiker “lonerobot.ui.character.HitchHiker” pos:[0,0] width:240 height:270
on HitchHikerRollout open do
(
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.HitchHiker+filetypes”).jpg
HitchHiker.displaystyle = (dotnetclass “lonerobot.ui.character.HitchHiker+displaystyles”).imagetext
HitchHiker.populate @”C:\Dotnet\maxfiles”
)
on HitchHikerRollout close do HitchHiker.housekeeping()
on HitchHiker thumbpicked sender args do
(
print args.FileName
print args.Image
)
)
createdialog HitchHikerRollout

It’s actually quite straightforward. You call the Populate method with a path string. You then handle the clicked icon with the ThumbPicked event. This has a property called filename, which is the currently selected file. (Should you wish to refer to this info outside the event you can get the filename from the hitchhiker.currentitem() property)

_______________________________________________________________

Methods

There are only a couple of actual public functions you can call on the control. You have already seen how you call populate(string) to set the control running. When this has been performed, you can call .getfiles() to get access to the file array in the same way you can in 3dsMax.

The other method available is CurrentImage(Multiplier as single)

This returns an dotnet image object of the current file, useful when using HitchHiker with a picturebox control. Large images can be resized with interpolation to speed the loading of the return image, or to give a low-res preview. If you want the original image, call this function with a multiplier of 1.0

The multiplier acts like an image size adjustment, the returnimageinterpmode property is what quality the image is drawn at.

There are a few properties to customise the layout of how HitchHiker displays the thumbnails. These are detailed next.

_______________________________________________________________

Properties

The following properties can be set on the control. For the examples, I am using the word HitchHiker to represent the instance of the control in your script, this is whether it is part of a 3dsMax rollout or a DotNet form class within 3dsMax.

.ButtonBackColor and .ThumbPanelBackColor

custombackcolor

buttonbackcolor3

Property Type : System.Drawing.Color
MaxScript :
HitchHiker.ButtonBackColor = (dotnetclass “system.drawing.color”).greenyellow
HitchHiker.ThumbPanelBackColor = (dotnetclass “system.drawing.color”).orange

Changes the Button/Panel background colour independently to the rest of the control.

_______________________________________________________________

.CurrentItem

Property Type : String
MaxScript : HitchHiker.CurrentItem()

Returns the full path (including filename) of the current or last selected item.

_______________________________________________________________

.CurrentMapFolder

Property Type : String
MaxScript : HitchHiker.CurrentMapFolder()

Returns only the path of the current or last selected item.

_______________________________________________________________

.DisplayStyle

imagetext

icontext


Property Type : LoneRobot.UI.Character.HitchHiker.DisplayStyles (Enum)
MaxScript :
HitchHiker.DisplayStyle = (dotnetclass “lonerobot.ui.character.hitchhiker+displaystyles).images
HitchHiker.DisplayStyle = (dotnetclass “lonerobot.ui.character.hitchhiker+displaystyles).icons
HitchHiker.DisplayStyle = (dotnetclass “lonerobot.ui.character.hitchhiker+displaystyles).imageText
HitchHiker.DisplayStyle = (dotnetclass “lonerobot.ui.character.hitchhiker+displaystyles).icontext
HitchHiker.DisplayStyle = (dotnetclass “lonerobot.ui.character.hitchhiker+displaystyles).text

This is an Enum to set the style of the display. Note the use of the + sign when instantiating an Enum via Mascript.

_______________________________________________________________

.FileType

Property Type : LoneRobot.UI.Character.HitchHiker.filetypes (Enum)
MaxScript :
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).tga
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).jpg
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).bmp
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).png
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).rpf
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).avi
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).wav
HitchHiker.filetype = (dotnetclass “lonerobot.ui.character.hitchhiker+filetypes”).tif

Enum to set the file type that HitchHiker searches for in the folder. If HitchHiker.RecursiveSearch is set to true, then Hitchhiker searches in all sub folders. If not, then it searches just the specified directory. When set to AVI, Hitchiker displays the frame halfway through the file, so that you avoid black frame thumb previews.

_______________________________________________________________

.Gap

gap2

gap2

Property Type : Integer
Maxscript : HitchHiker.Gap = 2

Value to set the spacing between the buttons on the HitchHiker panel. Property exposes the margin property of the embedded flowlayout panel.

Default:0

_______________________________________________________________

.ImageAlign

gap2

Property Type : System.Drawing.ContentAlignment
Maxscript :
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).BottomCenter
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).BottomLeft
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).BottomRight
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).MiddleCenter
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).MiddleLeft
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).MiddleRight
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).TopCenter
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).TopLeft
HitchHiker.ImageAlign = (dotnetclass “System.Drawing.ContentAlignment”).TopRight

Property for controlling the Image layout position on each button within the control.

_______________________________________________________________

.TextAlign

gap2

Property as above but for controlling the Text layout position on each button within the control.

_______________________________________________________________

.RecursiveSearch

Property Type : Boolean
Maxscript : HitchHiker.RecursiveSearch = True

Set to true to search subdirectories in the supplied directory. If set to False, only the main directory specifed is searched. Default:False

_______________________________________________________________

.ReturnImageInterpMode and .ThumbInterpMode

Property Type : LoneRobot.UI.Character.HitchHiker.Interpolation (Enum)
Maxscript :
HitchHiker.ReturnImageInterpMode = (dotnetclass “LoneRobot.UI.Character.HitchHiker+Interpolation”).Bilinear
HitchHiker.ThumbInterpMode = (dotnetclass “LoneRobot.UI.Character.HitchHiker+Interpolation”).low

Other enum interpolation types –

.Bicubic
.Bilinear
.Def
.High
.HQBicubic
.HQBilinear
.Low
.Nearest

This property is identical to ThumbInterpMode. It decides what quality GDI bitmap is returned. Different settings for this can increase thumbnailing speed at the expense of quality. If using to make an image browser, you could experieemnt with setting the ThumbInterpMode to low and the ReturnImageInterpMode to bilinear. This way, the control would generate the thumbs as quickly as possible but allow the viewed image to be high quality.

_______________________________________________________________

.SelectedBorderWidth

gap2

gap2

Property Type : Integer
Maxscript : HitchHiker.SelectedBorderWidth = 2

Value to set the width of the coloured outline around the active button on the HitchHiker panel.

_______________________________________________________________

.SelectedHighlight

gap2

gap2

gap2

Property Type : System.Drawing.Color
MaxScript : HitchHiker.SelectedHighlight = (dotnetclass “system.drawing.color”).yellow

Value to set the colour of the border around the active button.

_______________________________________________________________

.ShowMenu

gap2

Property Type : Boolean
MaxScript : : HitchHiker.ShowMenu= true

Enabled the display of the right-click menu to change the filetype and refresh the UI (The red icon at the top of the menu)

_______________________________________________________________

.ShowToolbar

gap2

Property Type : Boolean
MaxScript : HitchHiker.ShowToolbar= true

The toolbar gives access to common operations within the control, and allows the user to change directory, and search and display parameters. It is small format so that when used in the Max command panel, it can operate in the 160 pixel width neccesary for the panel.

toolbarref

HitchHiker Toolbar Options

_______________________________________________________________

.ShowTooltips

gap2

gap2

Property Type : Boolean
MaxScript : HitchHiker.ShowTooltips= true

Displays detailed image information. Look, TGA previews in DotNet! 🙂

This property calls a function that again uses managed services to gain image information from the MaxScript method GetBitmapInfo(). The information is then passed back to the dotnet assembly as a float, string, integer or boolean value according to the property.

_______________________________________________________________

.Sortby

Property Type : LoneRobot.UI.Character.HitchHiker.SortByOptions (Enum)
MaxScript :
HitchHiker.sortby = (dotnetclass “LoneRobot.UI.Character.HitchHiker+SortByOptions”).FileName
HitchHiker.sortby = (dotnetclass “LoneRobot.UI.Character.HitchHiker+SortByOptions”).LastWriteTime
HitchHiker.sortby = (dotnetclass “LoneRobot.UI.Character.HitchHiker+SortByOptions”).FilesizeAscending
HitchHiker.sortby = (dotnetclass “LoneRobot.UI.Character.HitchHiker+SortByOptions”).FilesizeDescending

Implements an Icomparer interface to provide custom sorting patterns for the resulting file array.

_______________________________________________________________

.TextImagerelation

Property Type : System.Windows.Forms.TextImageRelation
MaxScript : Hitchhiker.TextImagerelation = (dotnetclass “Windows.Forms.TextImageRelation”).ImageAboveText

Another method of text layout in the button controls. This property wraps the button property of the same name. For more control of the layout of the text and image use the .textalign and .imagealign properties

_______________________________________________________________

.Thumbnails

Property Type : LoneRobot.UI.Character.HitchHiker.ThumbNailSize (Enum)
MaxScript :
Hitchhiker.Thumbnails = (dotnetclass “LoneRobot.UI.Character.HitchHiker+ThumbNailSize”).Tiny
Hitchhiker.Thumbnails = (dotnetclass “LoneRobot.UI.Character.HitchHiker+ThumbNailSize”).Small
Hitchhiker.Thumbnails = (dotnetclass “LoneRobot.UI.Character.HitchHiker+ThumbNailSize”).Medium
Hitchhiker.Thumbnails = (dotnetclass “LoneRobot.UI.Character.HitchHiker+ThumbNailSize”).Large
Hitchhiker.Thumbnails = (dotnetclass “LoneRobot.UI.Character.HitchHiker+ThumbNailSize”).ExtraLarge

Sizes are as follows and are square.

Tiny = 24×24
Small = 50×70
Medium = 70×70
Large = 90×90
ExtraLarge = 150×150

These are to use as quick presets and are also used by the thumbnail buttons on the toolbar. To specify a custom thumbnail size, use the .thumbsize property

_______________________________________________________________

.Thumbsize

gap2

murray? Present.

Property Type : System.Drawing.Size
Maxscript : HitchHiker.thumbsize = dotnetobject “system.drawing.size” 200 60

Set a custom thumbnail size using this property. Useful if you want to show a larger thumbnail, for example when previewing video files. You may have noticed the filmstrip surround on the rollout. This was something I added to the thumbnails so that it mimicked the way Windows Vista displays video thumbnails in explorer.

_______________________________________________________________

Possible Uses for HitchHiker

The obvious uss for Hitchhiker is as an Asset Browser, but I thought I’d outline a way to use HitchHiker in a simple rollout to load scene audio. the code is as follows –

rollout AudioBot “Scene Audio File Loader” width:288 height:370
(
dotNetControl audiostuff “LoneRobot.ui.character.HitchHiker” pos:[1,0] width:286 height:471
on AudioBot open do
(
audiostuff.filetype = (dotnetclass “LoneRobot.ui.character.HitchHiker+filetypes”).wav
audiostuff.displaystyle = (dotnetclass “LoneRobot.ui.character.HitchHiker+displaystyles”).icontext
audiostuff.thumbsize = dotNetObject “System.Drawing.Size” 140 60
audiostuff.textalign = (dotnetclass “System.Drawing.ContentAlignment”).middleright
audiostuff.imagealign = (dotnetclass “System.Drawing.ContentAlignment”).middleleft
audiostuff.buttonbackcolor = (dotnetclass “system.drawing.color”).gray
audiostuff.populate “C:\Work Documents\W12 lipsync audio”
)
on audiostuff ThumbPicked sender args do
(
if keyboard.controlpressed do
(
if wavsound.isplaying then
(
stopAnimation()
wavsound.filename = args.filename
playAnimation()
)
else
(
wavsound.filename = args.filename
)
)
)
)
createdialog AudioBot style:#(#style_toolwindow, #style_sysmenu)

this will give you the following utility – Control click the thumbnail to load the wavfile into as scene audio.

audiobot

That’s it! I hope you find this control useful.

If you have any questions about usage, or any bugs/suggestions, please mail me through the website contact page. Please note that I will be updating HitchHiker periodically as I use it in my character pipeline tools.  HitchHiker has been production tested and works in x86 and x64 environments.

I repeat,  You will need 3dsMax 2010 in order for it to work.

HitchHiker is free

All I would ask in return is that if you use it for something useful or cool, give a credit as to where it was from!

download script

This document is included in the download as a help file in PDF format. You will need to download Acrobat reader in order to view it.