search

Redth / ResizetizerNT

Add SVG's and PNG's to your shared Xamarin Project
MIT License
318 stars 31 forks source link
hacktoberfest

readme

Resizetizer NT (for Workgroups and fun individuals)

Take SVG's and PNG's and automagically have them resized to all the different resolutions and included in your Xamarin Android, iOS, UWP, and WPF projects!

NuGet

Blog Post: redth.codes/resizetizer-nt-shared-images-for-xamarin

Video:

Shared Images in Xamarin with Resizetizer NT

History

A few years back I created a thing I called Resizetizer which helped solve the pain of resizing images to every single target density/resolution for iOS, Android, and UWP.

The original incarnation required that you define a .yaml file with all of your inputs and desired outputs. If you referenced this yaml file in your project and built it, the images would all be resized according to your config. You also had to specify all the various resolutions you wanted to output in the config file.

NT (New Technology)

This was great, but we could do better yet! The Resizetizer NT (New Technology) improves the story in a few ways:

  1. Add your images to your shared (netstandard2) projects with the SharedImage build action
  2. The config file is no longer necessary (or even a thing at all)
  3. Ideal resolutions for each platform are automatically created
  4. Resized images are automatically included in your Xamarin iOS, Android and UWP app head projects

How to use it

First you need to add the ResizetizerNT NuGet package to your shared code (netstandard2.0) project, as well as your Xamarin iOS/Android/UWP app projects. It's important to install it in all of your projects for this to work.

Next, add the images to your shared code (netstandard2.0) project as SharedImage build actions:

<ItemGroup>
  <SharedImage 
    Include="hamburger.svg"
    BaseSize="40,20" />
</ItemGroup>

Or you can specify it for each project like this :

<ItemGroup Condition="$(_ResizetizerIsiOS) == 'True'">
  <SharedImage Include="image.svg" BaseSize="44,44" />
</ItemGroup>

<ItemGroup Condition="$(_ResizetizerIsAndroid) == 'True'">
  <SharedImage Include="image.svg" BaseSize="50,50" />
</ItemGroup>

<ItemGroup Condition="$(_ResizetizerIsUWP) == 'True'">
  <SharedImage Include="image.svg" BaseSize="55,55" />
</ItemGroup>

<ItemGroup Condition="$(_ResizetizerIsWPF) == 'True'">
  <SharedImage Include="image.svg" BaseSize="60,60" />
</ItemGroup>

These images can be .svg or .png types.

BaseSize

Notice the BaseSize attribute which you will need to manually add. This is required for the resizer to know the baseline or nominal, or original (whatever you want to call it) density size. This is the size you would use in your code to specify the image size (eg: <Image Source="hamburger.png" WidthRequest="40" HeightRequest="20" />). In Android this is the drawable-mdpi resolution, on iOS you can consider it the @1x resolution, and on UWP it's the scale-100 resolution.

Referencing the Resized Images

When you build your app projects, they will invoke a target in your shared code project to collect all of the SharedImage items to process. These items will all be resized and automatically included in your app project as the appropriate type for an image resource.

You can reference images just like you normally would. The important thing to note is that if your input image source is .svg, you will actually reference a .png in your app.

In Xamarin Forms you would use something like:

<Image Source="hamburger.png" WidthRequest="40" HeightRequest="20" />

TintColor

If you'd like to render your images with a tint, you can set the TintColor attribute property on the SharedImage element. This renders your image with a color filter of "Source In" in SkiaSharp. This is particularly useful in cases where you have icons or simple images you'd like to render in different color than the source.

Example: <Image Source="hamburger.png" TintColor="#66b3ff" />

Planning

Bitmaps

By default if no BaseSize attribute is specified on the SharedImage item, the image should not be resized at all and instead simply included as a standard image in the app head project (Resources/drawable on android, etc.). If an BaseSize is specified, then the resizing rules apply to the image and different copies of the image should be made for the various display densities of each app head project.

Vectors

Vectors provide the best results for resizing an image to the display densities of each device. By default if no BaseSize attribute is specified on the SharedImage item, the vector should not resized at all and is simply included as a standard vector image in the app head project (Resources/drawable on android, etc.).

On Android the vector should also be converted to a Vector Drawable format resource.

Since by its very nature a vector’s size is unknown, if it is to be resized, a BaseSize must be included to support resizing to different display densities. Resize rules apply here.

Resize Rules

When an image needs to be resized for various display densities we need to know it's baseline or standard 1.0 device display density scale or factor in order to derive other image sizes to resize for other densities.

For the purpose of adding images to a project this is being called the BaseSize, and is specified in the project’s SharedImage item.

When no BaseSize is specified, on android this maps to drawable-mdpi, on iOS this is the equivalent of @1x, and on UWP it is scale-100.

When an BaseSize is specified this is considered the 1.0 scale factor for the images. All other density sizes are derived from this.

The original size is typically the expected density independent pixel size you intend to use the image in. For example this is the size you would intend to set for the RequestedWidth and RequestedHeight of a Xamarin.Forms Image control.

There are some default densities depending on target platform:

Android

iOS

UWP

WPF

Other Platforms

Tizen? MacOS? WPF?

IDE Integration

The proposed solution does not require but may benefit from some IDE customization or integration.

Adding items to a csproj manually is becoming more normal in sdk style projects.

Project Intellisense

It appears to be possible for us to add to the visual studio XSD for generating Intellisense inside project files so that attributes like BaseSize will show up as possible options.

Property Editor

You can already add images to a project which default to be in the None item group. You will be able to select SharedImage as a build action. In addition it may be possible to add properties to the property editor for things like BaseSize to be accessible from the IDE UI.

Other Features

There is an opportunity with things like vectors to provide some other interesting features:

Progress

Completed

In Progress