Saturday, March 10, 2012

Understanding KF8 Region Magnification

KF8 Fixed Layout Target Mag w/Live Text
There seems to be a fair amount of confusion and uncertainty concerning the region magnification feature in Kindle Format 8. This is certainly understandable considering the vague and often obscure treatment the subject received in Amazon's Kindle Publishing Guidelines, as well as the sketchy examples provided in the sample files themselves. Given the resources at Amazon's disposal one might think a top notch technical writer might be among them, but this doesn't seem to be the case.

In a recent post I provided a sample file of my own, complete with notes defining its component parts, but only marginally describing their several functions and variations. Therefore, in the interest of adding clarity to a rather muddled subject, I thought it might be useful to provide a bit more information here, in something of a mini tutorial. In addition, given the discussion in my last post concerning live text, I'll talk a bit more about that as well.


The first requirement for region magnification to function correctly is an entry in the metadata section of the content.opf file stating that the feature is active:
<meta name="RegionMagnification" content="true"/>
There are ostensibly two modes for using region magnification in KF8: one for text and one for images. As presented in the Guidelines the former applies to children's books and the latter exclusively to comics, with a "hybrid" method possible for zooming text in comics as well. But this is not actually the case. In fact, the region magnification method has nothing to do with the type of book at all, and you can use either one - or both - zoom methods at any time, regardless of the type of fixed layout you choose. It is the "RegionMagnification" entity that makes this possible, not the book type. Which brings us to...
<meta name="book-type" content="children"/>
<meta name="book-type" content="comic"/>
The allowed metadata values for the book-type are listed in the Guidelines as being either "children" or "comic," but the entity itself is also listed as being "optional." In other words, you can leave it out and still retain the region mag functions. While the description for the book-type entity states that it "provides additional reader functionality, specific to the classification of the book," it does not say just what that functionality is. Given that the sections dealing with children's book and comics focus primarily on region magnification features, the assumption is that that is the "additional functionality" referred to. But again, this proves not to be true.

So far as I can tell, with regard to the region mag functionality it doesn't matter which book-type you enter, in which order you put them if you enter both, or if you enter one at all. There is no change in region mag functions in any case. The only caveat to this is that the background image pinch-and-zoom feature discussed in my prior post is disabled with the "comic" book-type chosen (or entered first if both are given). But this is a feature overlooked by the Publishing Guidelines entirely, as if Amazon were unaware that it was possible. Certainly there is no description of it, or its use.

This leaves us with the question of what exactly the book-type is in there for. Perhaps this will be revealed in time as KF8 is rolled out further to apps and devices beyond the Fire. Possibly it has to do with product classification in the Kindle store, simply as a category definition, although the Guidelines state specifically that there is some sort of "additional functionality" involved. But what that is I cannot say.

[UPDATE: Later versions of the Kindle Publishing Guidelines changed the description of the book-type attribute to state that it removes reader functionality "which may not be relevant for certain books such as children's," and specifically lists the share function as being disabled.]

Making the issue even more perplexing is the fact that live text is available in fixed layout KF8 files so long as you don't enter a book-type: both the "comic" and "children" book-types disable all live text functions. But if you leave the book-type metadata line out of the OPF the fixed layout KF8 will have all the live text features active, as well as region magnification and full bleed spreads.

Thus, at present there is no clear reason to include a book-type at all, so far as I can see, except for...


A second point of obscurity with regard to KF8 is exactly how large image files can be and under what conditions. Prior to the inclusion of Section 5 (on Comics) in Version 2012.2 of the Guidelines, released just a few weeks back, the stated maximum for images was 256 Kb. But this in itself is inconsistent, since its single mention in Section 3.5.2 on page 19 is followed immediately by two apparently uncorrected references to the original size limit of 127 Kb. And now in Section 5.1 that restriction has seemingly been increased to 800 Kb - at least for graphic novels, since that is the only section in which it is mentioned. Therefore, it's unclear exactly what the limits are, and where they apply. This clearly illustrates why you need to hire a good tech writer in the first place (and an even better editor afterwards).

KindleGen itself seems to make no distinction in the file size so far as I can tell with regard to the book-type chosen: 800 Kb images compile successfully in either case. I've only had KG abort the conversion twice for images too large, but I have not been able to reproduce the variables that caused it (that's what you get for not controlling your variables).

As for KDP, my tests have shown that files with the book-type "children" or no book type at all are compressed upon upload at a somewhat higher rate than files with the "comic" value, a rate that varies considerably depending on the input file size. This is further complicated by the fact that KindleGen compiles image content differently for each book-type as well, with files of the "comic" type created at a larger size than those of the "children" type, both of them larger than the source epub itself. Thus, comics will have a better image quality overall than children's book in KF8, but not so much that the difference is disastrous, or even readily noticeable to the average viewer. And the live text functions are, to my mind, far more important to the user experience than a slight loss of image resolution.

That said, the fact that KDP compresses files at all is unacceptable to my mind, since it should be my choice how my content is presented. But as there is no way around it (aside from selling the files from your own website), for now we're stuck with it. You'll have to decide for yourself how much compression is acceptable.

As a side note, uploading the source .epub file directly to KDP has not proven successfully at all. It appears that KF8 uploads are restricted to KindleGen created source files.


1. Reasons For Using A Book-Type Value:
  • Possible (but currently unspecified) "added functionality" at some point
  • Lower file compression upon upload to KDP if "comic" value is used
2. Reason Against Using A Book-Type Value:
  • Live text possible in fixed-layout KF8, including full search, bookmarks, dictionaries, highlights and annotations
  • Background image pinch-and-zoom using double-tap outside of mag regions (functional with "children" but not "comic" book-type, but only if the img src insertion method is used)
  • MagTargets become visible on tap or hover, aiding in locating and positioning
  • Unnecessary for Region Magnification features to function
Alright, now that we've gotten all that out of the way, let's get on with the RegionMag details...


As mentioned, there are two different types of region magnification, respective to text or image content. And there are two alternate ways of presenting them: either with or without a background lightbox effect, in which the unzoomed areas are shaded. There are also a number of variables for each. The sample template I've provided in an earlier post has examples of them all so that you can view the code and use it as a guide or basis for your own project. The following explanations will presume you've downloaded that and read my prior posts on KF8, rather than wasting time rehashing all that here.

It helps to think of region mag as a series of boxes within boxes, or windows over windows, if you will. Each one is formatted separately and visible when activated or uncovered by deactivating the one on top. An example of a complete set of html elements for a fixed-layout page with region mag for text without a lightbox might be:
<div class="fs"> 
<img src="../images/example.jpg" alt="example" class="image"/> 
<div class="txt mag1"> 
<a class="app-amzn-magnify"
<div id="mag1-text">
<p>Content to be zoomed</p>
<div id="mag1-magTarget" class="target-mag1"></div>

The first div container holds the overall content, and is formatted in the css to the full size of a book page (which is not necessarily the size of the display, although it can be, as it is in my template). You then find the background image reference, which in this case uses the "comic" img src insertion method rather than the one found in the "children" example, which I don't find useful and won't go into here, since it locks the background image and we're discussing magnification functions here (for the record, I employ that method on the contents page of the template just so you view the code and use it if you like). Using the img src reference allows the background image to be zoomed by double-tapping on it, as discussed in my prior post, which has innumerable benefits for the reader.

Next we have our first div element containing the content to be zoomed: <div class="txt mag1">. The txt  and mag1 references refer to two separate entries in the css. In this case, the txt value simply defines the container as using absolute positioning, rather than the default relative as defined in the fs entity. You could just as easily use absolute positioning for the default and do away with this, but that will depend upon your page content and personal preferences. It's often easier to position text relative to its surroundings, although in fixed layout you'll likely use absolute positioning for text more often than not. The important point is to use absolute positioning to locate your content containers on the page; otherwise it will become really cumbersome when you start to position multiple div elements on the same page, such as in a graphic novel.

The mag1 value references the following css entry:
div.mag1 {
top: 50%;
left: 10%;
width: 80%;
This positions the content container starting halfway down the page and 10% in from the left. With the width set at 80% this leaves 10% for the right margin as well, so that there's no need to add a right: value. The height is determined by the content itself. The important thing to remember here is that these values position the container for the source content on the page: that is, the unmagnified text or image elements contained within (more on images in a bit).

The following JSON element is the code that enables and directs the magnification function. The app-amzn-magnify element and its subsequent data... tag have no reference in the css; rather, these call functions in the Kindle software itself, and must be written exactly as found up to the brackets, which contain the variables you control.

The first of these is a targetId which identifies the region to be magnified: the target. This reference must contain the relevant div class value as its first element (here mag1), followed by -magTarget. This element allows you to format the position and width of the area that can be tapped on to activate the zoom, but not its height - that is determined by its content, which can be formatted differently, or use the same formatting as its source content, as is done here. I'll discuss the the alternate formatting variation shortly. Keep in mind, this is NOT the magnified region itself, but the tap target; that is, the zone in which a double-tap will activate the zoom and display the magnified content. As mentioned earlier, one of the key benefits of deleting the book-type entry from the metadata, at least for content creators, is that it allows you to see the tap target (as a gray box) when you tap on it. This helps immensely with positioning (which, again, I'll get to in a bit). The tap target positioning data is entered in the css with an id selector:
#mag1-magTarget {
top: 40%;
left: 0%;
This allows you to create multiple tap targets on the same page by creating unique ids for each. You can see an example of how to do that on page one of the template. Since I haven't entered a width value in this example, and set the left positioning to 0%, the magnified region will span the full width of the screen (and as high as needed to accommodate the enlarged content). You can, of course, format the width as you see fit, but since the idea here is to magnify the content as much as possible, in most cases you will want to use as much of the display as you can. Also bear in mind that when you magnify content, the source content disappears, so you will want to position the magnified region to cover the area of the source content. However, there may be times you could use this to creative effect to make one thing disappear while another appears elsewhere. Use your imagination.

Now, if you look at the bottom line you'll notice that the targetId value appears as the first element in that string, as its id value. This in turn references a second div class value, here target-mag1, which is the css entity that allows us to format the magnified region and its content. This value can likely be whatever you want it to be, since it's just a reference to a css entry, but the convention used seems about as clear as you could want. The css entry for this in the template is: {
position: absolute;
display: none;
font-size: 150%;
padding: 15px;
border: 3px solid #000000;
border-radius: 8px;
background-color: white;
opacity: .95;
This is pretty straightforward formatting, but the important factor to mention here is that the font-size value is where you determine the amount of magnification for the enlarged text. This value is a percentage of the source value, so that if the source text is set to 120%, the zoomed text will be 150% of that. Of course, if you used pixels or ems to format your source text it will just multiply that amount.

In this example the magnified region is filled with a background-color, but you can insert an image instead:
background-image: url("../images/background.jpg");
This will set the referenced image as the background, with its position defaulting to the upper left corner and any excess beyond the borders hidden. You cannot move this image or resize it, although you can use different images in each instance. I use one the size of the full screen so that no matter the size of the mag region it will fill it up.

A note on the opacity value: it's essentially worthless. Unfortunately, it applies to all content included in the magnified region, text included, so you can't create a 50% transparent background without rendering your text a dim shade of grey. Not terribly useful, in my opinion, unless of course you want grey text in the first place. On page 2 of my template I left out any background at all so that the zoomed text appears over the fullscreen image. However, this is only helpful if there is no conflicting content in that image. If you work out how to make a semi-transparent background with black text in a mag target, let me know.

As for the magnified content itself, we need to return to our JSON object and discuss the last two entries. The value of the sourceId points us to the content to be zoomed: in this case mag1-text, which references the content found immediately below. In this case there is no relevant css entry, as this is simply a locator for the content, and the formatting is all done as normal within the content section itself. Thus, you can create and format any content you like as usual, and magnify it as is by simply enclosing it within the sourceId container. In this example, all content is magnified intact along with its formatting.

However, with fixed layout it may often be the case that magnifying the text as is will force it beyond the edges of the screen. For such instances as this, you can alter the formatting of the zoomed text by simply deleting the sourceId entry and its reference from the JSON object and source content section. You can then add alternately formatted content (or other other content entirely, located in a different position altogether!) to the magTarget at the bottom:
<div id="mag1-magTarget" class="target-mag1">
<p>blah, blah, blah...</p>
Finally, the last entry in our JSON object is the ordinal, which simply defines the order in which the magnified areas are shown if the user swipes from one to the next. This is useful primarily for graphic novels in which the panels may overlap or not run in a logical sequence down the page. Otherwise the sequence progresses in order as entered in the html.

That wraps up the text zoom feature. However, as this has run on longer than intended the image portion of this tutorial (including the lightbox feature) will have to wait until the next post. I'll try to work on it tomorrow, but it may take a day or two to get it finished. I hope you find this helpful, and that it didn't simply add more questions to those you had already.


The definitive guide to the Kindle fixed layout format, this fully revised and expanded tutorial will take you line-by-line through two working templates, including both the content and support files, as well as all layout and functionality features, explaining in painstaking detail what each element is for, and what your options are in every instance. Also included in the ebook is a code to download both templates for free!
Add to Cart
$9.99 [8.94 Mb]
Kindle reflowable .mobi format