Appendix - About Disk Images
Author: Copyright (C) 2014 by CiderPress authors

About Disk Images

Disk images are copies of entire Apple II floppy disks stored in a single file. There are several different ways to generate and store them, some designed for uploading to web pages, others for use with Apple II emulators. There are also a number of different ways of storing files on an Apple II disk, the most prominent being the DOS 3.3 and ProDOS filesystems, so opening an image file and getting at the files inside can be tricky.

CiderPress takes most of the pain out of opening disk images by automatically determining the storage format and filesystem for many common formats. You can view the format for an open disk image with the Archive Info feature, and you can attempt to override the automatic settings by enabling "Confirm disk image format" in Disk Image Preferences.

There are five attributes that must be determined before a disk image can be opened: outer format, image file format, physical format, sector ordering, and file system format.

Outer Format

Sometimes disk images are compressed with gzip or another program to reduce their size. If CiderPress sees a ".gz" or ".zip" extension, it will automatically uncompress the file when it is opened, and re-compress it if any changes are made.

CiderPress supports Zip/gzip compression in conjunction with all formats except ShrinkIt archives, so ".sdk.gz" and ".sdk.zip" won't open. Generally speaking, archives compressed with ShrinkIt don't compress much, so this is uncommon.

Image File Format

This is the format of the file that you have on your PC. The format is often indicated by the filename extension, e.g. ".sdk" for a disk packed with ShrinkIt. The disk image file formats that CiderPress handles, with their most common extensions, are:

Universal Disk Image .2MG, .2IMG

DiskCopy 4.2 .DSK, .DC, .DC6

Sim //e HDV .HDV

Dalton's Disk Disintegrator (DDD) .DDD

Formatted Disk Image (FDI) .FDI

Unadorned sectors .DSK, .DO, .PO, .D13, .HDV, .IMG, .RAW, .ISO

Unadorned nibbles .NIB, .NB2

NuFX (ShrinkIt) .SHK, .SDK

TrackStar .APP

The "unadorned" format refers to files that are nothing but disk data. The other formats have headers that must be removed before the data can be accessed. For some formats, such as NuFX and DDD, that data may need to be uncompressed before it can be used.

The Image File Format is reliably detected by CiderPress, and can't be overridden. If you think CiderPress has got it wrong, you can usually override its choice by changing the file extension.

Identifying DDD archives is tricky, because there is little information in the file format to distinguish it from an ordinary file. The only way to tell is to try to unpack the file and see if you run out of compressed data at roughly the same time as you output 140K of uncompressed data. Further complicating matters is that DOS DDD archives are stored as binary files but with a length of zero, so CiderPress has to guess that it's a DDD archive and then modify the length. CiderPress will adjust a DOS 'B' file if it has an address and length of zero, is at least 8 sectors long, and has angle brackets (<>) in the filename.

Please do not use DDD v2.0 under DOS; it has a bug that can cause the last sector on the disk to be corrupted. Because the DDD file format lacks any sort of checksum, the corruption can go undetected. Use DDD v2.1 or later under DOS. Better yet, use ShrinkIt to create your disk images.

TrackStar images are created and used by the TrackStar Apple II emulator hardware. This board was developed many years ago, and is rare today. The images are stored in nibble format, but have a variable length with a maximum of 6525 bytes per track. Standard ".nib" images use 6656 bytes per track, which means that converting from ".app" to ".nib" requires adding extra bytes in inter-sector gaps, and converting the other way requires finding and removing unnecessary bytes. Neither of these is 100% reliable, especially on copy-protected disks, so converting to and from ".app" only works well for unprotected disks.

The TrackStar's image maker creates 40-track and 80-track images. On a typical 40-track image, the last 5 tracks are empty, but some forms of copy protection used an additional track at the end of the disk. You can view the contents, if any, with the Disk Viewer. When converting to or from standard 35-track disk images, the last 5 tracks are dropped or zero-filled. 80-track images are like 40-track images but with "half tracks" stored as well. No other disk image format supports half-tracking, so CiderPress just skips every other track.

FDI images, created by "Disk2fdi", are similar to TrackStar in that they can have more than 35 tracks and use a variable-length track format. The "raw" images contain an image of the magnetic pulses captured from a PC floppy drive while reading an Apple II disk. FDI images may also contain nibble images of 3.5" disks, something no other format handles. The images are converted internally to variable-length nibble format, which means they can be converted to TrackStar format without losing data, but not to .NIB.

A ".ISO" image of a CD-ROM is essentially equivalent to ".PO". ".ISO" images of Macintosh-partitioned or HFS CD-ROMs can be accessed directly.

Physical Format

Once the headers are stripped and the data is uncompressed, you're left with one of two things: a stream of raw "nibble" data, stored exactly as it appeared when read from a 5.25" Apple II disk drive, or a stream of 256-byte sectors. This value indicates which of the two formats is used.

The most common nibble image format (.nib) has 6656 bytes per track, but occasionally you will find a ".nb2" image with 6384, or a ".app" TrackStar image with variable-length tracks. CiderPress supports all formats.

Sector Ordering

Apple II floppies typically have 16 sectors. The various Apple II operating systems used different "sector interleave" values for performance reasons, resulting in some confusion about where exactly a given track and sector resides in a sector-based disk image. Nibble images include the sector addresses, so there is no ambiguity.

There are four common ways to order the sectors, defined in terms of the operating system used to create the disk image:

Physical order: no interleave is used. Nibbles images always use this, and the Copy ][+ ".IMG" format is an "unadorned" file with this ordering.

DOS order: "-2" interleave is used. Programs commonly used for transferring 5.25" disk images will read the disk as DOS sectors, resulting in a DOS-ordered ".DO" image.

ProDOS order: "+2" interleave is used. ShrinkIt reads disks as a series of ProDOS blocks, and once extracted the disk is a ProDOS-ordered ".PO" image.

CP/M order: "+3" interleave is used. This would only be generated by a disk image creator running under CP/M, so you're unlikely to find an image in this order.

The sector order reflects the sequence in which the sectors were written into the image file. It allows us to convert between "physical" order and the stored order, which is important for proper handling of the "filesystem" attribute (described next).

It is possible to override the sector ordering value. If you do, CiderPress takes it as a recommendation, and will try that order first. If it is unable to process the image using the order you requested, it will go ahead and try Physical, DOS, and ProDOS.

13-sector ".d13" images are always stored in ascending sector order.

Filesystem Format

This is the key. It tells CiderPress how it should go about looking for files inside the disk image. The attribute defines not only how the files are arranged, but also how sectors should be pulled out of the image.

The supported filesystems are as follows:

Filesystem Sector Order

ProDOS ProDOS

HFS ProDOS

UCSD Pascal ProDOS

DOS 3.2/3.3 DOS

CP/M CP/M

RDOS 3.2 Physical

RDOS 3.3 ProDOS

UNIDOS/AmDOS DOS

OzDOS DOS

CiderPress also supports CFFA-style fixed partitions and Macintosh-style partition maps.

If the sector order for the filesystem format matches the Sector Ordering attribute, then reading the correct sector from the disk image is easy, because the image was written in exactly the same way that the filesystem needs to be read. If they don't match, then some amount of "sector swapping" is required to read the right sector from the right place.

If a disk doesn't actually have a filesystem -- perhaps it's an Apple II game that has its own disk format -- you will not be able to open it with CiderPress and view it as a collection of files. You can, however, open it with the Disk Sector Viewer. To provide the proper translation of sector numbers, you can use one of the "generic" filesystem formats. These don't define a file structure, but do let you describe the ordering of the disk. For example, if you use the "Generic DOS" entries, you will be able to read the disk exactly as you would with a "disk zap" utility. If you select the "Generic ProDOS" entry, you will get results equivalent to a ProDOS "block zap" utility.

The "generic" entries are only available when opening disk images with the Disk Editor.

Some disks have embedded DOS "sub-volumes", e.g. DOS 3.3 embedded in a ProDOS disk. See the embedded DOS volume section for more information. CFFA cards, partitioned hard drives, and CD-ROMs are handled similarly.